demuxe 0.3.0-beta.3

package/docs/BRANDING-MIGRATION.md

@@ -0,0 +1,77 @@
+# Beta.3 branding and migration audit
+
+Public package/executable: `demuxe`. Component: `<demuxe-player>`; exported class:
+`DemuxePlayerElement`. CSS variables use `--demuxe-*`. There is no legacy element
+alias: no public Demuxe npm release previously established that name.
+
+## Deplexr to Demuxe
+
+The attempted first publication as `deplexr` was rejected by npm's name-similarity
+check. It was never published. The replacement identity is `demuxe`; version
+`0.3.0-beta.3` remains the first proposed npm beta for this new package name.
+
+Update imports from `deplexr` and `deplexr/player` to `demuxe` and `demuxe/player`,
+the executable to `demuxe`, `<deplexr-player>` to `<demuxe-player>`,
+`DeplexrPlayerElement` to `DemuxePlayerElement`, and `--deplexr-*` variables to
+`--demuxe-*`. Asset examples now use `/assets/demuxe/`. Recopy assets with the new
+CLI into a fresh directory so the `demuxe-runtime.json` manifest describes them.
+Public `DEPLEXR_*` environment knobs become `DEMUXE_*`; older internal `WEBMPV_*`
+fallbacks remain as documented below. No Deplexr component or CSS aliases remain.
+
+The repository is `Jagalite/demuxe`. Historical Git commits, release tags, archive
+filenames, checksums and result records retain their original identity. They do
+not qualify renamed package bytes; a new clean tagged candidate must be built and
+tested before publishing Demuxe. The active local checkout directory may retain
+its old name until the workspace is reopened at a new location.
+
+The CLI is `bin/demuxe.mjs`; copied assets record `demuxe-runtime.json`. AudioWorklet
+registration and internal browser virtual URLs migrated together. Engine filenames
+remain `player.mjs`, `player.wasm`, `remux.mjs`, `remux.wasm`; their native C symbols
+and upstream names are not a public package identity and are preserved.
+
+Public docs, examples, install paths and package/source archive names use Demuxe.
+The following historical names are intentionally retained:
+
+* `LICENSE` and `docs/LICENSING.md`: the original copyright holder text remains
+  verbatim. Renaming a product does not rewrite attribution.
+* `results/`, `docs/validation/`, `docs/HANDOFF.md`, and experimental Markdown:
+  historical evidence, commands, paths and old artifact identities retain provenance.
+* `native/`, `patches/`, experimental native hooks: `webmpv_*` private C ABI symbols
+  remain to avoid cosmetic native changes. The source companion includes these
+  preferred sources and historical materials for GPL correspondence.
+* No legacy branded runtime filename or public custom-element alias is shipped.
+
+## Environment variable classification
+
+Maintained public knobs: `DEMUXE_SDK`, `DEMUXE_JOBS`, `DEMUXE_DECODER_SIMD`,
+`DEMUXE_REMUX_FFMPEG_DIR`, `DEMUXE_TEST_MEDIA`. Their old spellings remain fallback
+aliases in existing consumers; the new spelling wins. The standard clean-release
+recipe fixes the decoder/remux profile, regardless of optional overrides.
+
+`DEMUXE_RUNTIME_ROOT` is an internal qualification server mount used to test the
+installed archive, never a runtime API. Other unprefixed test knobs (`BETA_ARCHIVE`,
+`BROWSER`, `STREAMING_FIXTURE`, etc.) remain unchanged.
+
+The remaining legacy environment names are internal build/experimental harness
+wiring. Migrating their recorded configure scripts and historical experiments is
+technical debt, not a public runtime requirement. Inventory at this revision:
+
+* `WEBMPV_AUDIO_BRIDGE_H`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_BROWSER_DECODER`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_BROWSER_DECODER1`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_CACHE`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_DECODER_SIMD`: temporary compatibility alias.
+* `WEBMPV_DECODER_SIMD0`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_EM_CONFIG`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_ENGINE_DIR`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_FFMPEG_OBJ`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_FULL_MANIFEST_DIR`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_JOBS`: temporary compatibility alias.
+* `WEBMPV_KERNEL_OPT`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_LINK_OPT`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_MANIFEST_DIR`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_ORIGIN`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_PERFORMANCE_CONFIG`: internal build/experiment variable; retained for beta.3.
+* `WEBMPV_REMUX_FFMPEG_DIR`: temporary compatibility alias.
+* `WEBMPV_SDK`: temporary compatibility alias.
+* `WEBMPV_TEST_MEDIA`: temporary compatibility alias.

package/docs/COMPATIBILITY-EXPANSION.md

@@ -0,0 +1,181 @@
+# Compatibility expansion — 0.3.0-beta.1
+
+This increment extends Native, Hybrid and Software without adding a public mode.
+It is a functional beta increment; performance, physical output and production
+qualification remain separate. The original result files remain historical evidence.
+
+| Addition | Implementation | Functional acceptance |
+| --- | --- | --- |
+| External subtitles/fonts | SRT, ASS, SSA, WebVTT, TTF and OTF | Pixels, custom glyphs, track language/selection, seeks and mode changes |
+| Software AV1 | Pinned dav1d 1.5.1 | 8/10-bit decoding with browser codecs disabled, visible frames, seeks and filters |
+| Recorded format gaps | SBC hints, DFPWM/Dirac packet admission, SWF durations, RealAudio Matroska mapping, MPEG seek preroll | Corrected and original generated fixtures replayed separately |
+| 4K Software input | Configurable decode/allocation budgets | 3840×2160 input, bounded output, lower-budget rejection and rollback |
+| Remux resilience | One transient worker/MSE restart; short-hole recovery; AVC TS without audio | Recovery, bounded retries, seeks and automatic fallback at configuration changes |
+| Multichannel PCM | Stereo, 5.1 and 7.1 ring/output layouts | Per-channel values through native decoding and Web Audio, wrap/reset and device fallback |
+| HDR to SDR | zimg 3.0.6 plus FFmpeg Mobius tone mapping | Tagged PQ/HLG colors compared against a separate native reference |
+| Broader streaming | HLS/DASH rendition selection, finite segmented WebVTT, finite DASH periods and standard live audio/video | Playback, seeks, period boundaries, live reload/cancellation and resource cleanup |
+
+The final verification record below identifies the exact artifacts checked.
+
+## API
+
+```ts
+import {Player} from '/vendor/demuxe/index.js';
+
+const player = new Player(container, {
+  // Omit mode to allow automatic feature-aware selection.
+  audioOutput: 'auto',       // 'stereo' (default), '5.1', '7.1', or 'auto'
+  audioFallback: 'stereo',   // or 'reject' when the device cannot supply the layout
+  resourceLimits: {
+    maxDecodePixels: 3840 * 2160,
+    maxAllocationBytes: 128 * 1024 * 1024,
+  },
+});
+await player.addFont(fontFile);             // optional TTF/OTF; survives new sources
+await player.open(movieFile);
+await player.addSubtitle(srtOrAssFile, {
+  label: 'English', language: 'eng', select: true,
+});
+await player.setToneMapping('hdr-to-sdr');   // Software; 'off' restores normal filters
+await player.play();
+await player.destroy();
+```
+
+External mpv subtitles require Hybrid or Software. Automatic selection can move a
+Native session into an mpv mode; explicit Native pins reject that operation.
+`addTextTrack()` remains the separate browser URL/text-track API. `capabilities`
+reports `externalSubtitles`, `customFonts` and `externalTextTracks` separately.
+Subtitle tracks survive same-source mode/filter changes and clear on a new source.
+Fonts survive new sources and clear on destruction. Additions reopen transactionally,
+retaining the previous session if the candidate fails; these changes are not gapless.
+
+Each subtitle/font file is limited to 8 MiB. A player retains at most 16 subtitles
+and 16 fonts, with aggregate limits of 16 MiB and 32 MiB respectively. Use `select:
+false` to add an unselected subtitle; existing `selectTrack()` and
+`subtitleVisible()` controls continue to apply.
+
+Raw SBC lacks a reliable probe signature. Named `.sbc` Files are recognized; byte
+buffers or extensionless remote sources can supply a demuxer hint:
+
+```ts
+await player.open(bytes, {demuxer: 'sbc'});
+await player.openRemote({url, demuxer: 'sbc'});
+```
+
+## Output and resource contract
+
+Software's decode cap defaults to 8,294,400 pixels and can be reduced. The permitted
+individual FFmpeg allocation cap is 32–256 MiB, default 128 MiB. Each mpv Wasm engine
+starts at 128 MiB and may grow to 1 GiB. Canvas output remains within 1920×1080.
+A source replacement temporarily owns two engines, and browser decoder/DOM memory
+is additional. These are allocation bounds, not a universal real-time 4K guarantee.
+ArrayBuffers remain limited to 32 MiB; larger Files use bounded reads.
+
+`audioOutput: 'auto'` selects 7.1, 5.1 or stereo from Web Audio's advertised device
+capacity. An explicit PCM layout uses an mpv mode. `audioDiagnostics()` reports the
+requested layout, selected channels and device capacity. Native packet remux keeps
+its existing browser-controlled audio output. The multichannel functional tests use
+an explicit virtual output graph and verify each channel; they do not certify a
+physical surround receiver or speaker arrangement. Encoded surround bitstream
+passthrough and object-based audio rendering are not included.
+
+`toneMapping: 'hdr-to-sdr'` (constructor or setter) runs a linear-light conversion,
+BT.2020-to-BT.709 primaries conversion, Mobius compression, and limited-range BT.709
+output before user video filters. Inputs must carry valid color metadata. The
+reference checks cover tagged PQ and HLG; native HDR output, Dolby Vision dynamic
+metadata, display calibration and all mastering-peak combinations are not covered.
+
+## Streaming contract
+
+```ts
+await player.openRemote({
+  url: masterURL,
+  format: 'hls',
+  streaming: {maxBandwidth: 2_000_000},
+});
+await player.openRemote({
+  url: mpdURL,
+  format: 'dash',
+  streaming: {representation: 'video-720p'},
+});
+await player.openRemote({
+  url: liveURL, format: 'hls', streaming: {live: true},
+});
+```
+
+Selection chooses one rendition for the session; it does not continually switch
+bitrates. With `maxBandwidth`, the highest advertised bandwidth within the limit is
+chosen, or the lowest when none fit. With no preference, the highest is chosen.
+`representation` is a zero-based variant index string for HLS and a representation
+ID for DASH video. Associated audio/subtitle groups remain available.
+
+Finite HLS WebVTT playlists are combined into one indexed subtitle resource,
+preserving cue settings, absolute MPEGTS/LOCAL maps, wrap and discontinuities.
+The combined subtitle window is bounded to 1 MiB. Native cue queues are reset on
+seek. Rolling live subtitle-window replacement is not included in this profile.
+
+Finite multiple-period DASH is adapted to discontinuity playlists while FFmpeg
+continues to demux the compressed segments. This profile requires contiguous finite
+periods, stable track identities, fMP4 audio/video, aligned first segments, and
+SegmentTemplate/SegmentTimeline or SegmentList addressing. Separate byte-range
+SegmentLists, multiple video adaptation sets, period gaps/overlaps and changing
+track sets reject explicitly. Single-period DASH retains FFmpeg's demuxer.
+
+Standard HLS live and single-period dynamic DASH require `live: true`. Live seeking
+is limited by the upstream demuxer and available window; dynamic DASH seeking is
+not supported by the pinned FFmpeg demuxer. LL-HLS parts, DRM/encryption, live
+multi-period DASH, manifest patching and universal live-subtitle support remain out
+of scope. HTTP(S), origin/credential policy, bounded requests and cancellation still
+apply. Active resources retain the existing 16-handle/16-MiB bounds; generated
+manifest/subtitle resources have a separate 4-MiB budget. Each finite playlist has
+at most 10,000 segments. Live playback does not consume a finite lifetime-open cap.
+
+## Format and remux corrections
+
+The old comfort-noise fixture encoded 48-kHz timestamps for an 8-kHz decoder. Its
+replacement uses 8 kHz. The old generated RealMedia 14.4 stream had repeated zero
+packet timestamps and a truncated tail. Qualification uses valid RealAudio 14.4 in
+Matroska, whose mapping was missing from mpv's native Matroska demuxer. These fixture
+corrections do not establish support for those malformed historical files.
+
+DFPWM and generated intra Dirac/VC-2 NUT packets lacked keyframe flags; bounded
+codec-specific admission prevents their loss during startup/seek. Dirac admission
+checks for a sequence header and an intra picture parse unit. DFPWM decoder state
+is reset on seek. SWF ADPCM block durations now supply the missing audio timeline.
+One second of mpv demux preroll resolves the recorded MPEG-1/MPEG-2 seek cases.
+
+Native remux retries a transient worker/MSE fault once per explicit open, preserving
+source identity, position and playback intent. Small coded-range holes (up to half
+a second) can be crossed when a playing output stalls. Configuration changes and
+unrepairable timeline failures invoke the existing automatic Hybrid/Software
+fallback. Explicit Native pins report unsupported transitions. This is not a claim
+of gapless MSE reconfiguration for every sample-description change. Recovery and
+buffer diagnostics remain bounded and available under `diagnostics.backend.remux`.
+
+## Build and verification
+
+The locked-source engine recipe is `bash scripts/build-beta-engines.sh`. It builds
+portable dav1d and zimg into a separate playback dependency prefix. The complete
+patch series is replayed against verified upstream archives before updating source
+files, so overlapping patches remain idempotent and unrecognized edits are preserved.
+Optional YUV must be rebuilt with `npm run build:software-yuv`; it stays experimental.
+
+Generate functional fixtures with `npm run fixtures:compatibility`. This requires a
+host FFmpeg with SVT-AV1 and the existing DejaVu font archive. HDR reference generation
+uses the small native executable built by `bash scripts/build-color-reference.sh`
+(with a host zimg development package). Then run `npm run test:compatibility`.
+Fixture manifests record host encoder versions, commands and input hashes.
+
+Functional acceptance: 38 unit checks and 26 Chrome browser scenarios passed against
+unchanged input hashes. The repository record is
+`results/compatibility-expansion/2026-09-11T16-52-40.192Z/result.json`.
+PQ/HLG mean absolute RGB errors against the native reference were 1.857/0.709
+on the 0–255 scale. Six/eight-channel tests preserved each channel's expected
+PCM value through the native ring and Web Audio graph. The 4K-to-1080p case used
+161,087,488 bytes of Wasm heap in this short generated test.
+
+Package validation uses `node tests/beta-consumer.mjs` and
+`BROWSER=firefox node tests/beta-consumer.mjs`; those records include the installed
+archive SHA-256, type check, asset hashes and browser version. See repository
+`results/compatibility-expansion/README.md` for the completed regression and
+clean-consumer record. No production or long-duration qualification is inferred.

package/docs/LICENSING.md

@@ -0,0 +1,83 @@
+# Licensing and distribution
+
+## Original demuxe code
+
+Original demuxe code is licensed under **GPL-2.0-or-later**. The copyright notice
+is **Copyright (C) 2026 webmpv contributors**. See the root `LICENSE` for the grant,
+warranty disclaimer and complete GPL text. Upstream-derived files and dependencies
+retain their own notices and licenses.
+
+The distributed package is GPL-2.0-or-later. Commercial use is allowed under the
+license's conditions. Redistributing a covered combined work entails GPL source
+and license obligations; this package does not provide a proprietary embedding
+exception. A particular application's relationship to the library and distribution
+terms may need review.
+
+## Current linked engines
+
+These classifications follow the actual configured builds, not just the dependency
+names. `build/beta-build.json` records the configuration and hashes for each build.
+
+| Shipped artifact | Linked configuration | Applicable engine terms |
+| --- | --- | --- |
+| `web/engine-software-full/player.{mjs,wasm}` | mpv with `gpl=true`; FFmpeg with `CONFIG_GPL=1`, `CONFIG_VERSION3=0`, `CONFIG_NONFREE=0`; static libraries | GPL-2.0-or-later, plus retained component notices |
+| `web/engine-hybrid/player.{mjs,wasm}` | The same mpv and full FFmpeg archives, browser decoder bridge, and modified mpv subtitle renderer | GPL-2.0-or-later, plus retained component notices |
+| `web/engine-remux/remux.{mjs,wasm}` | Independent FFmpeg packet-only build; `CONFIG_GPL=0`, `CONFIG_VERSION3=0`, `CONFIG_NONFREE=0`; static libraries | FFmpeg library: LGPL-2.1-or-later; original wrapper and combined engine: GPL-2.0-or-later; retain the LGPL notices and source/relink materials |
+
+The optional YUV engine is outside the standard three-engine candidate and must be
+qualified and recorded separately before distribution.
+
+Additional linked components include libass (ISC), FriBidi and libplacebo
+(LGPL-2.1-or-later), HarfBuzz (MIT-style notices), FreeType (GPLv2 alternative for a GPLv2 combined distribution; retain
+both its FTL and GPLv2 texts), zlib (Zlib), libxml2 (MIT-style notices), dav1d
+(BSD-2-Clause), zimg (WTFPL), and Emscripten runtime libraries (the licenses and
+exceptions under `third_party/notices/emscripten`). Inspect each component's source
+headers for file-specific terms. Vulkan headers are build inputs; their notice is
+retained without claiming that a Vulkan runtime is shipped. The bundled DejaVu font
+has its separate copyright/license in `fixtures/FONT-LICENSE.txt`.
+
+This software uses FreeType. Portions are copyright the FreeType Project
+(https://freetype.org). The upstream notices identify the respective authors.
+
+The patched upstream sources, including `experiments/retained-subtitles/vo_libmpv.c`,
+retain their upstream licensing and any individual license headers. mpv's
+`Copyright` inventory also covers its C files without individual headers. The
+original-code license does not replace those upstream terms. The dated release record and `patches/` identify our modifications.
+
+## Source and build materials accompanying a distribution
+
+Ship the runtime archive and its matching `demuxe-*-source.tar.gz` together from the
+same download location. The source companion must contain:
+
+- The exact demuxe source revision, native wrappers, browser bindings, patches,
+  build scripts, source/toolchain locks, package lock, notices and font asset.
+- Every SHA-256-verified upstream archive in `sources.lock.json`, including the
+  SDK installer source, plus the actual installed Emscripten sources and runtime
+  library sources used in the build (excluding compiler caches).
+- Actual FFmpeg configuration headers and configure arguments, mpv configuration,
+  compiler/tool versions and hashes, the build log, and the engine build record.
+- Instructions to rebuild all engines and to relink the remux wrapper with a
+  modified FFmpeg. The supplied wrapper source and link command are part of the
+  static LGPL relinking materials; do not remove them from the source companion.
+
+The release manifest binds both archives to the source revision and engine hashes.
+Archive assembly must fail if the linked configuration or inputs disagree with the
+build record. Notices alone and a link to generic upstream sources do not substitute
+for matching source/build materials. Keep the companion downloadable alongside the
+runtime for recipients; do not rely on an unfulfilled written-source offer.
+
+The public download page and integrator documentation must identify the GPL engines
+and LGPL remux library and link the matching source archive. Preserve license texts,
+copyright notices and change identification when redistributing. Do not impose terms
+that conflict with the supplied licenses, including restrictions on the LGPL rights
+to modify/relink and debug those modifications.
+
+The build audit establishes the inputs/configuration and presence of these materials.
+It does not establish legal approval of a particular host application, EULA, store,
+patent jurisdiction, or distribution arrangement. Have those arrangements reviewed
+where needed, especially before embedding the GPL engines in a proprietary product.
+
+References: [FFmpeg's license and distribution guidance](https://ffmpeg.org/legal.html),
+[mpv's copyright and licensing statement](https://github.com/mpv-player/mpv/blob/v0.40.0/Copyright),
+[GPL version 2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html),
+[LGPL version 2.1](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html).