OnlyPlayer

OnlyPlayer Browser Extension
OnlyPlayer is a Chromium-compatible browser extension that turns any modern browser into a PotPlayer-inspired local media workstation. It focuses on fast directory browsing, rich playback controls, and a customizable UI so users on locked-down machines can still enjoy a full-featured player without installing native software. The interface is icon-first: virtually every action is represented by glyphs, while the limited textual hints auto-localize to the browser language.

Key Experiences
Directory-first playback - pick local folders via the File System Access API, auto-index supported audio/video formats, and build smart playlists represented by icon badges (audio note, film reel, favorites star, etc.).
Unified media core - one player component handles audio and video with seamless switching, shared shortcuts, unified icon-based transport controls, and consistent theming.
PotPlayer-inspired tools - quick bookmark jump list, A-B repeat, playback speed presets, frame-step, audio EQ, subtitle search/loading, and snapshotting to browser storage, each surfaced through glyph-led toolbars with translated tooltips.
Always-on controls - floating mini-player, global media keys (Media Session API), picture-in-picture, and background playback managed by the extension service worker with symbol-only overlays.
Stateful experience - per-file resume points, last-played folders, user-defined profiles (e.g., "Movie mode", "Podcast mode"), and syncable settings via chrome.storage, with locale-aware labels wherever text is required.
Tech Stack Choices
Layer Technology Reasoning
UI React + TypeScript + Tailwind Fast iteration, typed component contracts, theming flexibility.
Build Vite + @crxjs/vite-plugin Efficient HMR while targeting Manifest V3, easy bundle outputs.
State Zustand + Immer Lightweight yet powerful store for playback/session state.
Media Native <audio>/<video> + Media Source Extensions Maximum codec compatibility within browser constraints.
File Access File System Access API (Chromium) with fallbacks Enables folder picking and streaming local files securely.
Background Chrome Extension Manifest V3 service worker Handles global shortcuts, context menus, background scanning.
Styling Tailwind + CSS variables + icon font/SVG sprite sheet PotPlayer-like skins, symbol-driven UI, dark/light themes.
i18n @lingui/core (or similar) with navigator language detection Minimal text auto-localizes; tooltips and accessibility labels track browser locale.
Feature Inventory (v1 Focus)
Folder picker UI with recursive scan, format filters, quick search, and icon-coded media types.
Tabbed library views (All media, Audio-only, Video-only, Favorites, Recents) with glyph tabs and localized screen-reader labels.
Primary player panel with:
Timeline scrubber, waveform mini-visualizer for audio
Speed control (0.25x-4x), pitch-lock, A-B repeat
Subtitle loader (local + URL) and styling panel
Audio filters: equalizer presets, channel balance, volume boost
Icon-grid action board replacing textual buttons, with hover/click tooltips translated dynamically.
Queue management (drag and drop order, autoplay next, shuffle, loop) with icon badges (loop arrows, shuffle crossing, etc.).
Bookmarking and chapter markers, export/import as JSON.
Snapshot and GIF capture (video) saved to sandboxed storage with download option.
Keyboard shortcuts mirroring PotPlayer defaults with configurable bindings.
Media Session integration for OS-level media buttons and notification controls.
Picture-in-picture and compact mini-player window.
Settings sync (profiles, UI layout, recent folders) with optional cloud backup via browser sync storage, plus locale pack download/update flow.
Media Format Support
OnlyPlayer builds on Chromium's native <audio>/<video> decoders, so compatibility is tied to what your browser already ships. The current behavior is:

Confirmed working Notes
MP4 (H.264 + AAC), WebM (VP9/Opus) Recommended for video playback.
MP3, AAC/M4A, Opus/OGG, WAV Audio playlists (M4A must be AAC, not ALAC/DRM).
Commonly unsupported Reason
HEVC/H.265 MP4, AV1 on old Chromium versions Codec absent on many systems.
FLAC, APE, DTS, proprietary containers (RMVB, TS, FLV) Browser cannot decode natively; consider transcoding.
When the browser cannot decode a file, the player surfaces a warning and skips playback. Users can convert files to MP4 (H.264 + AAC) or MP3/AAC for the broadest compatibility.

Stretch Ideas
DLNA or SMB discovery through an optional helper service for network media.
WASM-powered extra codec pack (for example FFmpeg.wasm) for unsupported formats.
Web lyrics and subtitle auto-fetch via configurable providers.
Remote control via WebRTC between devices logged into the same extension account.
Development Workflow
pnpm install
pnpm dev - launches Vite dev server plus extension reloader.
pnpm build - outputs production bundle under dist/.
Load dist as an unpacked extension in Chrome or Edge.
Testing and QA
Unit and component tests with Vitest plus Testing Library.
Playback regression harness relying on sample media fixtures.
Manual smoke scripts covering folder scan, playback, PiP, shortcuts.
Visual regression checks ensure iconography stays consistent across locales; localization snapshots verify translations.
Status
🚧 Planning phase. See plan.md for milestones and implementation sequence.