drop-player

A comprehensive, universal, open-source React media player powering drop.mov.

動画（HLS / プログレッシブ）、音声、画像、PDFに対応。 ひとつのコンポーネントで、ソースURLからメディア種別を自動判定します。

インストール

npm i drop-player lucide-react

必須 peer dependencies: react >=18, react-dom >=18, lucide-react >=0.300

オプション（必要な場合のみ）:

クイックスタート

import { Player } from 'drop-player';
import 'drop-player/styles.css';

function App() {
  return (
    <div style={{ width: 640, height: 360 }}>
      <Player sources="https://example.com/video.mp4" />
    </div>
  );
}

スタイルシートは必須です — drop-player プレフィックスのクラスとCSS変数が定義されています。

コンポーネント

VideoPlayer や AudioPlayer などは可読性のためのエイリアスです。すべて同じ PlayerProps / PlayerRef を共有し、メディアモードはソースURLから自動判定されます。種別が混在する場合や不明な場合は Player を使ってください。

対応メディア

ブラウザ専用のランタイムです。SSRフレームワーク（Next.js, Remix, Astro 等）での import は安全で、サーバー上では何も描画せず、クライアントで有効化されます。

ソース

// 文字列 — 拡張子からタイプを推定
<VideoPlayer sources="https://example.com/video.mp4" />

// オブジェクト — HLSとオリジナル画質のフォールバック
<VideoPlayer sources={{ url: 'stream.m3u8', originalUrl: 'original.mp4' }} />

// 配列 — ソースセレクターを表示
<VideoPlayer sources={[
  { url: 'stream.m3u8', label: 'HLS' },
  { url: 'original.mp4', label: 'Original' },
]} />

// 明示的なMIMEタイプ — URLに拡張子がない場合に便利（例: CDN、署名付きURL）
<Player sources={{ url: 'https://cdn.example.com/abc123', mimeType: 'video/mp4' }} />

// null — エラーUIを表示
<VideoPlayer sources={null} />

メディア種別はパスの拡張子（.mp4, .m3u8, .pdf, .jpg, …）または mimeType から判定されます。

Props

Propsは4つのグループに分かれています:

<VideoPlayer
  sources="video.mp4"
  className="rounded-lg"
  crossOrigin="anonymous"
  poster="poster.jpg"

  playback={{ autoPlay: true, volume: 0.8 }}
  ui={{ features: { saveCapture: true, copyCapture: true }, locale: 'ja' }}
  slots={{ topRightOverlay: <Badge /> }}
  events={{ onPlay: () => log('playing') }}
/>

トップレベル

playback — PlayerPlaybackConfig

ui — PlayerUiConfig

マーカータイプ

Marker は判別ユニオン型です。type によってシークバートラック上の表示形状が変わります:

共通フィールド:

import type { Marker } from 'drop-player';

const markers: Marker[] = [
  { time: 10, type: 'circle', snap: true },
  { time: 30, type: 'line' },
  { time: 60, type: 'square', color: 'red' },
  {
    time: 90,
    type: 'custom',
    content: <div style={{ ... }}>ラベル</div>,
  },
];

<VideoPlayer sources={url} ui={{ markers }} />

slots — PlayerSlots

Note: overlay はデフォルトで pointer-events: none です。操作可能にしたい子要素には pointer-events: auto を指定してください。

events — PlayerEvents

Features

ui.features で個別のコントロールをON/OFFできます。省略したキーは defaultFeatures を引き継ぎます。

2つのプリセットをエクスポートしています:

import { noFeatures } from 'drop-player';

// Default — most controls on
<VideoPlayer sources={url} />

// Add capture buttons to defaults
<VideoPlayer sources={url} ui={{ features: { saveCapture: true, copyCapture: true } }} />

// Remove loop from defaults
<VideoPlayer sources={url} ui={{ features: { loop: false } }} />

// Build from scratch
<VideoPlayer sources={url} ui={{ features: { ...noFeatures, playButton: true, fullscreen: true } }} />

時間表示形式

ui.timeDisplayFormats で、時間表示をクリックした際に切り替わる形式を制御します。2つのプリセットをエクスポートしています:

import { defaultTimeDisplayFormats, allTimeDisplayFormats } from 'drop-player';

// デフォルト — 経過/合計と残り時間
<VideoPlayer sources={url} />

// タイムコードとフレームを追加
<VideoPlayer sources={url} ui={{ timeDisplayFormats: allTimeDisplayFormats }} />

// 映像制作向け — フィート+フレーム（35mm）を追加
<VideoPlayer sources={url} ui={{
  timeDisplayFormats: [...defaultTimeDisplayFormats, 'timecode', 'feet-frames'],
  filmGauge: 16,
}} />

// 音楽向け — 小節:拍を追加
<AudioPlayer sources={url} ui={{
  timeDisplayFormats: [...defaultTimeDisplayFormats, 'bars-beats'],
  bpm: 92,
  timeSignature: '4/4',
}} />

// 単一形式に固定（クリックしても変わらない）
<VideoPlayer sources={url} ui={{ timeDisplayFormats: ['timecode'] }} />

フレームレートはHLSマニフェストから自動検出されます。プログレッシブソースの場合は ui.frameRate を明示的に設定してください。

テーマ

.drop-player のCSS変数を上書きできます:

@import 'drop-player/styles.css';

.drop-player {
  --drop-player-blue: oklch(70.7% 0.165 254.624);
  --drop-player-yellow: oklch(85.2% 0.199 91.936);
  --drop-player-green: oklch(79.2% 0.209 151.711);
  --drop-player-red: oklch(70.4% 0.191 22.216);
  --drop-player-muted: oklch(55.2% 0.016 285.938);
  --drop-player-marker-circle: var(--drop-player-yellow);
  --drop-player-border-radius: 8px;
}

Ref API

PlayerRef 経由でメソッドを呼び出せます:

const ref = useRef<PlayerRef>(null);

<VideoPlayer ref={ref} sources={url} />

// Later:
ref.current?.play();
ref.current?.seek(30);

エラーハンドリング

events.onError と slots.errorDisplay は name で種別を判別できる Error を受け取ります:

組み込みUIは ui.locale に従ってエラーメッセージをローカライズします。独自の表示にするには slots.errorDisplay を使ってください。

翻訳

組み込みロケール: 'en' と 'ja'。ui.locale で切り替えます。

ロケールの追加や文字列の部分上書きには ui.translations を使います:

<VideoPlayer
  sources="video.mp4"
  ui={{
    locale: 'en',
    translations: {
      play: 'Reproducir',
      pause: 'Pausar',
      mute: 'Silenciar',
      unmute: 'Activar sonido',
      fullscreen: 'Pantalla completa',
      exitFullscreen: 'Salir de pantalla completa',
    },
  }}
/>

ベースロケールの文字列に対して差分だけ指定すればOKです。

カスタムストレージ

プレーヤーの設定（ミュート状態など）はデフォルトで localStorage に保存されます。storageKey でキーのプレフィックスを変えたり、storage でバックエンド自体を差し替えられます。

// Custom namespace
<VideoPlayer sources="video.mp4" storageKey="my_app" />
// Keys stored as: my_app_muted, my_app_volume, etc.

// Custom backend (e.g. Supabase)
const supabaseStorage = {
  getItem: (key: string) => {
    // Read from Supabase cache or return null
    return localStorage.getItem(key);
  },
  setItem: (key: string, value: string) => {
    localStorage.setItem(key, value);
    supabase.from('preferences').upsert({ key, value });
  },
  removeItem: (key: string) => {
    localStorage.removeItem(key);
    supabase.from('preferences').delete().eq('key', key);
  },
};

<VideoPlayer sources="video.mp4" storage={supabaseStorage} />

StorageAdapter は getItem・setItem・removeItem の3メソッドを実装します。戻り値は同期的に返す必要があるため、リモートバックエンドの場合はローカルキャッシュ経由で非同期に同期してください。

ユーティリティ

プレーヤー外でも使えるヘルパー関数:

import {
  formatTime, formatTimecode, secondsToFrames, parseFrameRate,
  formatFeetFrames, formatSecondsFrames, formatBarsBeats,
} from 'drop-player';

formatTime(125);                    // "02:05"
formatTime(3661);                   // "01:01:01"
formatTimecode(125.5, 30);          // "00:02:05:15"
formatTimecode(125.5, '30000/1001');// "00:02:05:14" (29.97fps)
secondsToFrames(10, 24);           // 240
parseFrameRate('30000/1001');       // 29.97...
formatSecondsFrames(83.5, 30);     // "83+15"
formatFeetFrames(10, 24, 16);      // "15+00"
formatBarsBeats(10, 120, '4/4');   // "5:1"

ライセンス

MIT

Changelog

1.5.5

Features

• Add drop-player/utils sub-path export — pure formatter functions (formatTime, formatTimecode, secondsToFrames, parseFrameRate, formatSecondsFrames, formatFeetFrames, formatBarsBeats) importable without React, safe for Server Components

1.5.4

Features

• Add overlay slot — full-area overlay layer between media and controls (pointer-events: none by default)

1.5.2

Bug Fixes

• Fix SSR safety: guard ResizeObserver usage in useElementWidths hook with typeof check to prevent ReferenceError in server-side rendering environments

1.5.0

Breaking Changes

• Remove ambient light feature — ambientLight has been removed from PlayerFeatures, VideoState, VideoCoreRef, and all related UI/CSS. If you were using features={{ ambientLight: true }}, remove it.

1.4.0

Features

• Add responsive controls bar — controls dynamically collapse into an overflow menu based on available width
• Add overflow menu (⋯) that groups secondary controls (ambient light, PiP, playback speed, capture) when space is limited
• Split capture button into separate CopyCaptureButton and SaveCaptureButton controls
• Add useFeedback hook for transient action feedback (e.g. "Copied!")
• Add useMediaQuery and useElementWidths hooks for responsive layout

Bug Fixes

• Fix marker positions not rendering correctly on the seekbar
• Fix SEO: add prerender script for demo site, update llms.txt / llms-ja.txt

1.3.0

Breaking Changes

• Marker API redesigned — Marker is now a discriminated union. Replace type: 'scene' with type: 'circle'. The old type: 'custom' (no-op) now requires content: ReactNode.
• slots.seekbarOverlay removed — use type: 'custom' markers instead.
• CSS variable --drop-player-marker-scene renamed to --drop-player-marker-circle. --drop-player-marker-custom removed.
• Snap is now opt-in per marker — add snap: true to each marker that should snap. Previously snap was always active when markers were present.

Features

• New marker types: 'circle' (renamed from 'scene'), 'line', 'square', 'custom'
• snap?: boolean — enable snap-to per marker (default: false)
• snapThreshold?: number — per-marker snap distance in px (default: 12, only used when snap: true)
• content: ReactNode — render arbitrary content on the seekbar track at a specific time (type: 'custom')
• Named marker types (CircleMarker, LineMarker, SquareMarker, CustomMarker) exported from package root

1.2.5

• Revert 1.2.4

1.2.4 (deprecated)

• Fix Webpack/Turbopack build error (Module not found) when optional peer dependencies are not installed — reverted, webpackIgnore prevents bundlers from resolving installed packages at runtime

1.2.3

Bug Fixes

• Fix controls overlay not recoverable on mobile for Image, PDF, and Audio modes — tapping the content area now toggles controls visibility, matching Video behavior
• Fix player blocking page scroll on mobile — allow vertical scrolling (pan-y) for all media types; only block scroll when Image/PDF is zoomed in

1.2.2

Bug Fixes

• Fix controls UI not showing on tap for Image, PDF, and Audio modes

1.2.1

Bug Fixes

• Fix PDF cleanup on unmount (add destroyWorker call)
• Improve StatusOverlay accessibility and translation handling
• Fix re-exported types from package root

1.2.0

Features

• Add pdf.js integration as optional peer dependency for canvas-based PDF rendering with real zoom, pan, and page navigation
• Add PageNavigation control (prev/next page with ChevronUp/ChevronDown icons)
• Add PdfCoreRef imperative handle (zoomIn, zoomOut, resetZoom, nextPage, prevPage, goToPage)
• Add keyboard shortcuts for PDF mode (ArrowUp/ArrowDown for pages, +/-/0 for zoom)
• Add swipe gesture for PDF page navigation (disabled when zoomed)
• Fallback to browser-native <object> rendering when pdfjs-dist is not installed

Improvements

• PDF pages fit container at 100% zoom (no excess margins)
• Zoom re-renders via pdf.js for crisp vector text (debounced 150ms with immediate CSS feedback)
• Page change resets zoom to 1x
• Controls and title auto-hide after 3 seconds for image and PDF modes (consistent with video/audio)
• Source change resets readiness state so loading overlay covers stale content
• Add tabular-nums to zoom level display
• Controls overlay now has proper z-index to remain visible during loading

1.1.7

Features

• Add seekStep playback option to configure arrow key skip duration in seconds (default: 10)
• Add seekStepButtons feature flag for skip forward/backward buttons
• Add showStatusOverlay UI option — pill-style overlay showing player actions (play/pause, seek, volume, speed, quality, zoom, loop)

1.1.6

Features

• Add multi-source navigation (prev/next buttons, swipe gesture, keyboard navigation)
• Add sourceNavigation feature flag to show/hide prev/next buttons
• Add time display formats: seconds-frames, feet-frames, bars-beats
• Auto-detect frame rate from HLS level metadata
• Add CSS color variables for easier theme customization

Improvements

• Expand touch/click target for seekbar and volume slider thumbs without changing visual appearance
• Style dropdown scrollbar to match player theme

1.1.5

Improvements

• Add drag-to-seek on audio waveform (click to seek, drag to scrub)
• Add accessibility attributes on audio waveform area (role="slider", aria-valuemin/max/now)
• Improve PDF error handling: pre-validate URL reachability, fire onError with errorNetwork on failure
• Suppress AbortError from play/pause races

Bug Fixes

• Fix audio player not showing error state when loading fails

Documentation

• Add CSS variables reference table, feature presets, Translations, Custom storage, Utilities sections to README

1.1.4

Improvements

• VideoPlayer, AudioPlayer, ImageViewer, PdfViewer now set media mode directly, skipping source type inference
• Add default aspect-ratio per media mode (video: 16/9, audio: 32/9, image: 4/3, pdf: 1/1.414), overridable via --drop-player-aspect-ratio
• Warn when URL has no recognizable extension and mimeType is not provided

Bug Fixes

• Fix min-width: 100% redundancy on player container

1.1.3

Bug Fixes

• Fix hydration mismatch caused by PiP support detection running during SSR

1.1.2

Bug Fixes

• Unify mouse/touch handling with Pointer Events for consistent drag-to-seek and controls toggle
• Improve HLS fatal error handling: network errors now trigger fallback, media error recovery limited to one attempt
• Type hlsConfig as Partial<HlsConfig> instead of Record<string, unknown>
• Add network-error to FallbackReason type
• Rename legacy @dropmov/player references to drop-player in console warnings

Styles

• Responsive timestamp position in controls bar

1.1.1

Features

• Add storage prop for custom StorageAdapter (replaces default localStorage)
• Add translations prop for custom i18n string overrides
• Widen locale type from 'en' | 'ja' to string for custom locales
• Stabilize React hooks to avoid unnecessary re-renders with object props

Styles

• Fix ambient light mode rendering
• Reposition timestamp display

1.1.0

Features

• Add storageKey prop to customize localStorage key prefix (default: drop_player_, custom: <storageKey>_)
• Persist and restore muted state across sessions via localStorage

Breaking Changes

• Remove persistenceKey prop and playback position persistence feature
• Remove onPositionSave / onPositionRestore event callbacks

1.0.7

Bug Fixes

• Fix tooltip not dismissing on Safari and touch devices
• Fix multiple tooltips displaying simultaneously
• Auto-dismiss tooltips after timeout on touch interactions
• Fix muted state behavior

1.0.6

Features

• Add playback speed selector control
• Add Picture-in-Picture (PiP) button control

Bug Fixes

• Fix tooltip position not recalculating when content changes

1.0.5

Features

• Support hlsConfig prop for custom hls.js configuration
• Tune ABR settings for smoother adaptive bitrate switching

Bug Fixes

• Dynamically import waveform-data to reduce initial bundle size
• Fix tooltip position

1.0.4

Maintenance

• Disable sourcemap output and enable minification in build
• Remove unnecessary documentation files

1.0.3

Breaking Changes

• Remove Tailwind CSS dependency from library output; all styles are now plain CSS with drop-player-* BEM classes
• Consumers no longer need Tailwind — just import drop-player/styles.css

Bug Fixes

• Fix controls and seekbar not rendering (Tailwind utility classes missing from build output)

1.0.2

Bug Fixes

• Fix player and controls not spanning full width in flex/aspect-ratio layouts

1.0.1

Maintenance

• Update dependency packages

1.0.0

Initial Release

• Video and audio player component with custom controls
• Keyboard shortcuts support
• Marker/chapter support (scene markers, custom markers)
• Playback speed control
• Volume control with mute toggle
• Fullscreen support
• Ambient light effect
• Multiple source selector
• Customizable theming via CSS variables
• Error handling with retry