Client-side video player — play any video file in the browser without a server.
Do NOT use auto-memory (~/.claude/projects/.../memory/). All project context lives in this file.
Uses pnpm workspaces. The root package is the core library (playsvideo). The app/ directory is a separate workspace for the React media player.
pnpm install # install all workspace deps
pnpm -w run <script> # run a root workspace script
pnpm --filter app dev # run the media player dev serverBefore considering work done, all of these must pass:
pnpm -w run typecheck # tsc --noEmit
pnpm -w run test:unit # vitest run tests/unit (fast, no fixtures needed)
pnpm -w run lint # biome lint .
pnpm -w run format # biome format --write . (then verify no unstaged changes)Integration tests (pnpm -w run test:integration) require test fixtures in tests/fixtures/.
src/pipeline/— core pipeline modules (demux, mux, segment plan, audio transcode, codec probe)src/adapters/— platform adapters (node-ffmpeg, node-ffprobe, wasm-ffmpeg)src/engine.ts— PlaysVideoEngine class (worker, hls.js, subtitles — no UI)src/worker.ts— browser web worker (demux + segment processing)src/pwa-player.ts— browser entry point (thin UI wiring to engine)tests/unit/— fast unit tests (no external dependencies)tests/integration/— tests requiring ffmpeg/ffprobe and test fixturestests/e2e/— playwright browser testsapp/— React media player (separate workspace, see below)
React app with library management at /app. Separate workspace with its own package.json, vite.config.ts, tsconfig.json.
app/src/db.ts— Dexie IndexedDB schema (library, directories, playlists, settings)app/src/scan.ts— File System Access API directory walker + IDB syncapp/src/hooks/useEngine.ts— React hook wrapping PlaysVideoEngine lifecycleapp/src/pages/Library.tsx— video library grid with folder pickerapp/src/pages/Player.tsx— video player page- Uses
import { PlaysVideoEngine } from 'playsvideo'via workspace link
- TypeScript with ES modules (
.jsextensions in imports) - Biome for formatting and linting (not ESLint/Prettier)
- vitest for testing
- mediabunny for demux and mux (fMP4)
- hls.js for playback (custom
fLoaderfor on-demand segments — no service worker)
Implementation tactical docs live under docs/tactical/ and use zero-padded
numeric filenames. The next tactical created under this convention is
000-{subject}.md; after that, allocate the next unused number and add it to
docs/tactical/README.md. Completed tacticals are execution records, not the
source of continuing guidance.
Focused, living topic docs live under docs/topics/. Before working on a
continuing concern, look for and read its topic doc. Update it when work changes
the concern's status, contract, evidence, validation, gaps, or recommended next
direction. Create a focused topic when continuity across sessions or commits
would be valuable, but do not create one for every small standalone change or
broaden a nearby topic into a catch-all.
Adopt these conventions incrementally. Existing architecture, reference, status, and implementation-plan docs do not need to move solely for consistency. Architecture and reference docs own durable system shape and external facts; topic docs own current truth for a focused continuing concern; tactical docs own bounded implementation slices and execution records.
See docs/tactical/README.md and docs/topics/README.md for the local indexes
and templates. The root topics.md is separate: it registers exact Topic:
strings used to thread related commit series.
Aim for a subject of at most 65 characters and strictly wrap commit bodies at
72 columns. Use a concise, result-oriented subject that remains scannable in
git log --oneline. Never mention Claude, AI, or any AI assistant in commit
messages; write them as human development history.
For non-trivial commits, include a concise synthesis of the originating request or motivating observation and the key implementation direction. Preserve enough context for a future maintainer to understand or approximately re-derive the change without recording digressions, secrets, or a verbatim conversation. Mechanical or small self-evident changes may use a one-line message.
When commits form a related series, append one or more exact
Topic: <string> trailers after the body. The first commit chooses the string;
later commits copy it verbatim so git log --grep "Topic: ..." finds the
series. Prefer the matching docs/topics/ filename slug when the series
implements a documented topic. Use multiple trailers when needed and omit them
for standalone commits with no expected follow-up. Before starting a series,
scan root topics.md and register any new topic string there.
- ONLY for small MEMFS segment operations. NEVER for full-file operations (WORKERFS is catastrophically slow, MEMFS can't hold large files). Do not use ffmpeg for subtitle extraction or any task requiring full file access.
- Two bundles:
src/vendor/ffmpeg-core-audio/(1.5MB, audio-only) andsrc/vendor/ffmpeg-core/(31MB, full) - Audio transcode works now; video transcode planned (hardware decode scenarios)
- Lazy-load only when transcode is actually needed
- Source packets → concatenate raw bitstream → ffmpeg → parse ADTS output → EncodedPackets
ffmpeg -f {sourceCodec} -i input -c:a aac -ac 2 -b:a 160k -f adts output.aacsourceCodecfromTranscodeOptions.sourceCodec: ac3, eac3, dts, mp3, flac, opus- Codec probe (
audioNeedsTranscode) decides passthrough vs transcode per platform
- Worker keeps demux handle open, processes segments on-demand when hls.js requests them
FfmpegRunnerinterface abstracts node:fs vs MEMFS- Concurrent ffmpeg.wasm calls are serialized (shared MEMFS corruption)
- See
docs/mediabunny-integration.mdfor current fork state and maintenance plan - Source of truth should be one local checkout at
~/code/references/mediabunny - Key:
collectPacketsInRangeneeds{ startFromKeyframe: true }for video - API:
EncodedVideoPacketSource.add(packet, { decoderConfig }),Mp4OutputFormat({ fastStart: 'fragmented', onMoov, onMoof, onMdat }),NullTargetwith callbacks for streaming
- Our plan may differ from ffmpeg's segment count by 1–2 segments (ffmpeg's fMP4 init extraction absorbs keyframe cuts). This is cosmetic and does not affect playback.
Changelog-driven releases. The changelog entry must exist before the release script will run.
- Add entry to
CHANGELOG.mdunder## [x.y.z](move items from[Unreleased]) - Commit the changelog update
- Run:
bash scripts/release.sh x.y.z- Validates version format and clean working tree
- Requires matching
## [x.y.z]in CHANGELOG.md - Runs green gates + lib build
- Updates package.json version, commits, creates
vx.y.ztag
- Push:
git push && git push origin vx.y.z - CI picks up the tag → runs gates → publishes to npm → creates GitHub Release with changelog notes
| File | Purpose |
|---|---|
CHANGELOG.md |
Keep a Changelog format, required before release |
scripts/release.sh |
Version bump, validation, commit, tag |
.github/workflows/publish.yml |
CI: tag push → npm publish + GitHub Release |
- Entry:
import { PlaysVideoEngine } from 'playsvideo' - Lib build:
pnpm -w run build:lib(tsc viatsconfig.lib.json, excludes Vite-specific files andsrc/app/) - Trusted publishing via OIDC (
id-token: write) — no npm token needed, configure on npmjs.com package settings
Site is hosted with Cloudflare Workers Static Assets at playsvideo.com.
pnpm -w run deploy:site # build both sites + atomically deploy Worker/assets
pnpm -w run deploy:worker # deploy Worker with existing dist-site/ + app/dist/
pnpm -w run deploy # alias for deploy:sitescripts/deploy.sh— stages the app underdist-site/app/and invokes Wrangler once; Wrangler uploads only changed asset hashesworker/index.js— Cloudflare Worker that handles clean URL aliases and the/app/*SPA fallbackpublic/_headers— cache policy (no-cache for HTML/SW/manifest, immutable for hashed assets). No COOP/COEP headers needed (seedocs/no-shared-array-buffer.md)- The legacy R2 bucket is retained as a rollback source but is not bound to the Worker.
If testing on physical Chromebook/ChromeOS hardware, read and follow
~/code/chromeos-testbed/skills/SKILL.md. Start with:
~/code/chromeos-testbed/bin/chromeos doctorFor PlaysVideo-specific device state and workflows, also read
~/code/dotfiles/projects/playsvideo-chromebook-offline-media.md. It is the
runbook for building and deploying the extension, reopening it after reload,
managing the test media, retaining folder permission, and validating offline
playback.
The audio-only bundle is built via Docker on the desktop machine. To rebuild after changing ffmpegbuild/Dockerfile.ffmpeg-audio:
# 1. Commit and push changes (Dockerfile changes must be on remote)
git push
# 2. Build on desktop (has Docker) — pulls, builds, copies to vendor dir
ssh desktop "cd ~/code/playsvideo && git pull && bash ffmpegbuild/build.sh"
# 3. Copy built files back
scp desktop:~/code/playsvideo/ffmpegbuild/out/ffmpeg-core.js \
desktop:~/code/playsvideo/ffmpegbuild/out/ffmpeg-core.wasm \
src/vendor/ffmpeg-core-audio/Build config: ffmpegbuild/Dockerfile.ffmpeg-audio (decoders, encoders, filters, etc.)
JSTorrent (~/code/jstorrent/) imports playsvideo from dist/. After changing source, run pnpm -w run build:lib to rebuild — pnpm dev only serves source via Vite and does not update dist/.
- ffmpeg source:
~/code/references/ffmpeg(key file:libavformat/hlsenc.c) - mediafox (wiedymi's player):
~/code/references/mediafox