The "Build pinned Linux Embedded MPV runtime" job failed twice on 2026-08-11
because www.freedesktop.org answered GitHub runners with HTTP 418 for the
fontconfig tarball. The Linux builder curled a single pinned URL with no
fallback, so upstream rate-limiting reddened the build.
Route downloadArchive() through the shared downloadPinnedSource() helper the
macOS builder already uses, and pin a mirror for each single-host source:
fontconfig and libdisplay-info (freedesktop-hosted) plus freetype, which the
macOS builder already mirrors. Each mirror was downloaded and verified to hash
to the existing pin. The curl hardening flags and assertArchiveMatchesPin are
unchanged, and the helper verifies every candidate against the same SHA-256,
so a mirror serving different bytes is rejected rather than used.
Unlike macOS, the Linux manifest keeps sourceUrl at the canonical pinned value
even when a mirror served the bytes: notice generation and the Snap publication
boundary compare that field against the immutable pin. A used mirror is logged
instead.
build-linux-runtime.mjs now imports the downloader, so download-pinned-source.mjs
joins the released source-archive tooling set (otherwise the archive would ship
a build script it cannot run) and the Linux runtime cache key.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* feat(packaging): register IPTVnator as the .m3u/.m3u8 handler
Every runtime path for an OS-supplied playlist existed, but no packaging
metadata claimed the file types — so the OS never offered IPTVnator as a
handler and `open-file` could not fire from Finder.
`fileAssociations` declares one entry per extension. Electron Builder derives
all three platform registrations from it: macOS `CFBundleDocumentTypes` (the
prerequisite for `open-file`), the NSIS registry entries, and, on Linux, the
desktop entry's `MimeType` plus `/usr/share/mime/packages/iptvnator.xml` for
deb/rpm/pacman. Neither platform needs a dedicated icon — both fall back to the
app icon.
Declaring `MimeType` under `linux.desktop.entry` would not have worked:
Electron Builder assigns the association-derived value *after* spreading that
object, so an explicit key there is silently overwritten. The per-association
`mimeType` fields produce the same entry through the supported path.
Registering the types also exposes a gap in the delivery side. The generated
Linux `Exec` ends in `%U`, so file managers hand over a percent-encoded
`file://` URI rather than a path, which `createPlaylistOpenRequest` would have
resolved into a bogus relative path. It now decodes a `file://` candidate
before the extension check. Suppressing the `%U` instead would mean putting an
exec code in `linux.executableArgs`, which also passes it to the app as a real
argument.
Verified on macOS against a signed packaged bundle: Launch Services lists the
app as a `public.m3u-playlist` handler, and an LS-initiated open imports the
playlist both on a cold launch and against the already-running process.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(playlist): open every playlist of a multi-file selection
`%U` is the plural exec code, so selecting several playlists in a Linux file
manager is one launch carrying one argument per file. Both argv paths called
`extractPlaylistOpenRequestFromArgv`, which returned at the first match, so
everything after the first playlist was silently discarded — a gap this PR
itself opened by making the desktop entry reachable in the first place.
The extractor is now plural and returns every match in argument order, and the
queue gained `enqueueAll` so a selection is pushed under a single flush: a
delivery that fails partway leaves the untouched remainder queued in arrival
order rather than interleaved.
Covered by unit tests over a mixed argv (percent-encoded `file://` URI, a
non-playlist argument, a second URI) and by a new Electron E2E that launches
with two playlist arguments and asserts both are imported.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* chore(deps): bump actions/setup-node from 4 to 7
Bumps [actions/setup-node](https://github.com/actions/setup-node) from 4 to 7.
- [Release notes](https://github.com/actions/setup-node/releases)
- [Commits](https://github.com/actions/setup-node/compare/v4...v7)
---
updated-dependencies:
- dependency-name: actions/setup-node
dependency-version: '7'
dependency-type: direct:production
update-type: version-update:semver-major
...
Signed-off-by: dependabot[bot] <support@github.com>
* chore(ci): allow actions/setup-node v7 in the Snap workflow policy
The Snap supply-chain policy test pins the exact major of every action
the build workflow may use, so bumping actions/setup-node in the
workflow without updating BUILD_ACTION_ALLOWLIST fails
publish-snap-workflow.test.mjs.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: 4gray <serega05@gmail.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* chore(deps): bump actions/cache from 4 to 6
Bumps [actions/cache](https://github.com/actions/cache) from 4 to 6.
- [Release notes](https://github.com/actions/cache/releases)
- [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md)
- [Commits](https://github.com/actions/cache/compare/v4...v6)
---
updated-dependencies:
- dependency-name: actions/cache
dependency-version: '6'
dependency-type: direct:production
update-type: version-update:semver-major
...
Signed-off-by: dependabot[bot] <support@github.com>
* chore(ci): allow actions/cache v6 in the Snap workflow policy
The Snap supply-chain policy test pins the exact major of every action
the build workflow may use, so bumping actions/cache in the workflow
without updating BUILD_ACTION_ALLOWLIST fails
publish-snap-workflow.test.mjs.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: 4gray <serega05@gmail.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
The packaging verifier bounded `iptvnator_mpv_helper --runtime-probe` with
RUNTIME_PROBE_TIMEOUT_MS (3s) — a constant it shares with the application's own
startup capability gate. Three seconds is a tight budget for a helper that
dlopens libmpv plus EGL/GL/GBM, and the Flatpak profile is closest to that edge
because the helper runs inside the sandbox against its bundled closure: on
#1277 the job failed three consecutive reruns and passed on the fourth with no
code change, while the concurrent master job passed.
Give the verifier its own budget rather than raising the shared one. The app's
probe is a blocking spawnSync on the Electron main process, so a hung helper
must not stall window creation, and a timeout there degrades gracefully to the
native-view fallback. Nothing waits on the packaging probe but the CI job,
which already has its own 120-minute bound, while a premature kill reports a
healthy package as broken.
- PACKAGE_VERIFICATION_PROBE_TIMEOUT_MS (15s) and
PACKAGE_VERIFICATION_PROBE_MAX_ATTEMPTS (2) join the frozen probe contract;
RUNTIME_PROBE_TIMEOUT_MS stays at 3s for the application gate.
- runBoundedRuntimeProbe() retries only on ETIMEDOUT, repeating the identical
bounded launch (same command, args, env, maxBuffer, killSignal) and
announcing the retry on stderr so a degrading trend stays visible.
Fail-closed behaviour is unchanged. A hard timeout is the one probe outcome
that says nothing about the payload; spawn errors (a missing helper, a wrapper
launched instead of the real ELF), termination by signal, nonzero exits and
malformed or wrong-protocol lines all still fail on the first attempt, and a
helper that keeps hanging still fails once both attempts are spent.
The four new/extended verifier tests cover retry-then-success (asserting the
second launch is identical to the first), exhausted timeouts still rejecting,
four non-timeout verdicts each probing exactly once, and the attempt bound
itself. Setting MAX_ATTEMPTS to 1 fails four of them.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Supersedes #1249, #1245 and #1247, which each rewrote the full-commit pins in
publish-snap.yaml while the same SHAs are asserted in three packaging test
files — merged separately, every one of them left those tests red.
actions/checkout v4 -> v7 (docker.yml from v6), actions/upload-artifact
v4 -> v7, actions/download-artifact v4 -> v8. New pins verified against the
upstream tag refs: checkout 3d3c42e5 = v7.0.1, upload-artifact 043fb46d =
v7.0.1, download-artifact 3e5f45b2 = v8.0.1.
download-artifact v8 changes two things on the Snap publish path, both in our
favour: a digest mismatch now fails the run instead of logging a warning, and
decompression is skipped for non-zip Content-Types (our artifact is a normal
upload-artifact zip, so unchanged). checkout v7's fork-PR block only applies to
pull_request_target/workflow_run, neither of which exists here.
Pipeline audit follow-up: reduce wasted runner time on PRs and tighten CI
security, without reducing what actually gets validated.
Runner-time waste:
- Concurrency with PR-only cancel-in-progress on CI, E2E, and docker-build,
so a new push cancels the previous commit's still-running checks. Non-PR
runs use the unique run_id as the group, because GitHub keeps at most one
pending run per group even with cancel-in-progress: false — a shared ref
group could silently drop a queued master run.
- paths-ignore for docs-only changes (Markdown, docs/, .plans/, .codex/,
.claude/) on the Electron build matrix and the E2E suites; E2E also skips
apps/website/**. The build workflow keeps apps/website/** because its Linux
job builds the website to verify AppStream assets. Tag pushes are
unaffected: GitHub does not evaluate paths filters for tags.
- PRs lint affected projects only; master pushes keep the full run-many.
Lint-global inputs (eslint.config.mjs, tools/eslint/**) now mark all 41
lint projects affected, including the run-commands targets database and
packaging, so the max-lines baseline cannot be widened without lint.
Hardening:
- Explicit least-privilege permissions on CI, E2E, and build-and-make; the
create-release job keeps its job-level contents: write. The repository
default workflow token was switched to read-only.
- New actionlint job (image pinned by digest, shellcheck at warning+), with
the shared-anchor false positive suppressed in .github/actionlint.yaml.
Fixed one real finding: unquoted $GITHUB_OUTPUT.
- .github/dependabot.yml: weekly cadence, minor+patch grouped per ecosystem
(npm, GitHub Actions, Docker), majors stay individual PRs.
Docs updated: CLAUDE.md, docs/architecture/nx-workspace-boundaries.md, and
docs/architecture/validation-map.md now describe affected-lint on PRs and the
E2E path-filter exceptions.
Port the embedded mpv frame-copy pipeline to Windows with WGL rendering and named shared memory. Includes packaging validation, platform gates, tests, and architecture documentation.
* feat(embedded-mpv): Linux frame-copy helper via headless EGL
Port the frame-copy engine's native layer to Linux (PORTING.md items 1-4):
- frame_helper_gl.h: platform GlContext abstraction. macOS keeps the CGL
path (moved verbatim); Linux acquires an EGL display in order
surfaceless-Mesa -> default display -> GBM render node, binds a 3.2 core
desktop-GL context surfaceless (1x1 pbuffer fallback), and hands mpv
eglGetProcAddress. The helper's own GL calls link against glvnd
libOpenGL, so no display server is required.
- frame_shm.h: portable frame_shm_now_ns() (CLOCK_MONOTONIC) shared by the
helper and the reader addon, replacing the macOS-only
clock_gettime_nsec_np(CLOCK_MONOTONIC_RAW); producer and consumer stay on
the same clock.
- embedded_mpv_frame_reader.c: real implementation now also on __linux__
(the code was already POSIX apart from the clock call).
- binding.gyp: OS==linux executable branch for iptvnator_mpv_helper linking
system libmpv (-lmpv) + EGL/OpenGL/gbm, with rpaths for $ORIGIN/lib and
the build-time library dir. The in-process addon still does not link
libmpv - the ban only binds in-process, the helper is out of process.
- build-embedded-mpv.js: system-dev fallback on Linux (LIBMPV_INCLUDE_DIR
or /usr/include) so a distro libmpv-dev install builds without staging a
vendored runtime; a pre-set LINUX_NATIVE_LIBRARY_DIR now wins over the
vendored lib dir.
Verified on Ubuntu 25.04 / i7-1165G7 (Iris Xe): lavfi smoke per PORTING.md
(idle->loading->playing snapshots at 4 Hz, aspect-fit generation bump
g1 1280x720 -> g2 960x720 for a 4:3 source), reader probe 60 fps at
1080p60 with 0 torn reads, clean quit with no leaked processes or shm.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(embedded-mpv): enable the frame-copy engine gates on Linux
Flip the TypeScript side of the Linux port (PORTING.md item 5). A shared
dependency-free predicate, isFrameCopyPlatformSupported() (linux any-arch,
darwin arm64-only), now backs all four gates so they cannot drift:
- main.ts: the persisted Settings toggle promotes to the env flag on Linux
too (this runs before window creation and controls the sandbox relax).
- EmbeddedMpvNativeService.isFrameCopyEngineActive/isFrameCopyAvailable.
- EmbeddedMpvFrameCopyAdapter.isSupported.
getSupport() ordering: the frame-copy branch moves above the Linux-only
native-engine prerequisites - the X11/Xwayland display-server check and
the system-mpv-on-PATH probe only bind the --wid native engine, while the
frame-copy helper renders offscreen (headless EGL) and links libmpv
itself. createSession() also skips resolving the native window handle for
frame-copy sessions, which the adapter ignores anyway, so native-Wayland
sessions no longer trip the window-handle assertion.
Settings copy: the i18n frame-copy description now says macOS (Apple
Silicon) and Linux in all 18 languages; stale macOS-only doc comments in
the settings/support interfaces updated alongside.
Tests: platform-gate matrix for the adapter (darwin arm64/x64, linux
x64/arm64, win32) and service specs covering Linux activation under
native Wayland, macOS arm64 staying active, macOS x64 staying native, and
the skipped window handle for frame-copy sessions.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(packaging): CI + package guards for the Linux frame-copy helper
- build-and-make.yaml: install libegl-dev/libgl-dev/libgbm-dev on the
Linux runner (the helper's EGL backend needs them now that the helper
target builds on Linux), and verify the built helper exists and DOES
link libmpv - the inverse of the addon's no-libmpv rule, which still
holds and stays validated.
- electron-after-pack.cjs: strip iptvnator_mpv_helper from packaged Linux
apps. It links the build host's system libmpv, which end-user systems
cannot be assumed to have; the support probe treats the missing helper
as frame-copy-unavailable (dev-build-only engine until the
bundled-runtime staging milestone).
- frame_helper_gl.h: log the chosen EGL display tier to stderr (the
adapter mirrors helper stderr), so bring-up problems on exotic setups
are diagnosable.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(embedded-mpv): document the Linux frame-copy port
- architecture doc: frame-copy section covers Linux (EGL display tiers,
build deps, package strip), Linux support matrix notes the frame-copy
exception to the X11 + system-mpv requirements, Linux measured baseline.
- RESULTS.md: Ubuntu 25.04 / i7-1165G7 (Iris Xe) measurement rows via the
production helper + reader probe; viewport-size claim reproduced.
- PORTING.md: Linux marked done with pointers to what changed; Windows
remains the open port and its perf gate the open decision.
- CLAUDE.md + tools/embedded-mpv/README.md: platform scope, Linux dev
build requirements, system-headers fallback, helper strip.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(embedded-mpv): commit the Linux frame-copy measurement probe
linux-frame-probe.mjs reproduces the RESULTS.md Linux rows: spawns the
production helper, attaches the frame-reader addon to the announced shm
generation, and reports new-frame fps, copy wall time, produce->copy age,
torn reads and pixel spread. Usage documented in RESULTS.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(embedded-mpv): address multi-agent review findings on the Linux port
Confirmed findings (each verified by 3 adversarial reviewers):
- CI would fail to link the helper: -lOpenGL needs the unversioned glvnd
libOpenGL.so, shipped only by libopengl-dev, which neither the runner
images nor the previous apt line provide. Added to the workflow and to
every documented Linux build-dep list.
- The new 'test -x' dist guard could never pass: webpack's dist asset
copy drops file modes (helper arrives as 0644). The guard is now
'test -f'; electron-after-pack.cjs restores the execute bit on packaged
helpers (also fixes packaged-macOS spawns); the support probe now
requires X_OK, so a mode-stripped helper reads as frame-copy-unavailable
and falls back to native instead of failing spawn with EACCES.
- The Settings frame-copy toggle was unreachable in exactly the Linux
states the port targets: the native-Wayland and missing-system-mpv
unsupported payloads omitted frameCopyAvailable, and toggle visibility
derives solely from it. Both returns now advertise availability.
Also from review:
- build-embedded-mpv.js keeps the old graceful-skip contract when the new
system-dev fallback finds libmpv-dev but the GL/EGL/gbm dev stack is
missing (previously such machines skipped; a hard electron-build
failure was a regression).
- createSession derives the window-handle skip from the dispatched addon
instead of re-evaluating the engine gate, so the two cannot disagree.
- The render thread logs the GL renderer string (surfaceless Mesa can
silently pick llvmpipe on non-Mesa-primary systems; now diagnosable —
verified 'Mesa Intel Iris Xe' on this machine).
- Specs pin the new semantics: frameCopyAvailable advertised while native
is unsupported (Wayland / no mpv), frame-copy supported without a
system mpv, and the handle-skip test disposes its session through the
owning adapter.
- Docs: PORTING.md file map reflects the frame_helper_gl.h seam for the
Windows porter; helper-strip removal correctly gated on milestone 4
(bundled libmpv), not milestone 3; RESULTS.md preamble notes the
RAW->MONOTONIC clock change; stale '(macOS)' scope comments updated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(embedded-mpv): address Greptile/Codex review comments
- Sandbox gate requires a usable helper (Greptile P1, security): the
main.ts env promotion now also probes for an executable
iptvnator_mpv_helper before relaxing the window sandbox — a stale
opt-in on packaged Linux (helper deliberately stripped) or after a
cleaned native build no longer costs a sandboxless launch for an
engine that cannot activate. Helper discovery (addon candidate paths +
X_OK probe) moved into embedded-mpv-frame-copy-platform.util.ts,
shared by main.ts and the service; the service keeps thin instance
wrappers so tests can stub per scenario. New util spec pins the
platform matrix, candidate resolution, and the execute-bit semantics.
- Stale frame-copy artifacts on skipped builds (Codex P2): cleanOutput()
now also removes iptvnator_mpv_helper and
embedded_mpv_frame_reader.node, so a failed/skipped rebuild cannot
leave a previous helper advertising frame-copy support against a
runtime the build just declared unavailable.
- Multiarch default lib dir (Greptile P1, partially refuted): -l
resolution never depended on our -L (the compiler's built-in search
paths include the Debian/Ubuntu multiarch dir — proven by the green CI
run linking with a nonexistent -L dir), but the system-dev fallback
now defaults to /usr/lib/<multiarch-triple> when present so the -L
flag and the helper's baked rpath point somewhere real.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(embedded-mpv): harden Linux frame-copy port
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* spike(embedded-mpv): frame-copy pipeline prototype (helper + shm ring + Electron viewer)
Standalone macOS spike for the frame-copy unification direction from the
2026-07-10 analysis: a helper process renders mpv offscreen into a GL FBO,
reads frames back through an async PBO ring, and publishes BGRA frames into
a 3-slot POSIX shm seqlock ring; a minimal Electron viewer copies the newest
frame via a plain-C N-API addon and uploads it to a WebGL canvas per rAF.
First numbers on M1 Pro (see spike README): 4K60 HEVC hwdec sustained at
60 fps end to end, ~1.2 ms shm copy + ~3.5 ms texture upload, ~10 ms
produce-to-upload age, zero torn frames. Remaining gates: weak hardware,
long-run pacing, HDR, latency flash test.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* spike(embedded-mpv): add RESULTS.md measurement log with M1 Pro baseline
Structured per-machine table with repro commands so the pending Intel Mac
and Windows iGPU runs can be appended and compared one-to-one.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* spike(embedded-mpv): pacing/judder instrumentation + 50/25 fps and HDR gate results
Viewer now measures inter-frame intervals on both clocks (present side and
producer side): stddev/p99/max, late-frame counters vs the producer's median
interval, and a cumulative LONGRUN summary every 30 s. The addon exposes the
producer timestamp (produceMs) for this.
Measured on M1 Pro: 50 fps and 25 fps cadences are clean (late frames only
at startup; residual jitter is 120 Hz rAF grid quantization, bounded by one
display tick), and 4K25 HDR10 PQ/BT.2020 is tonemapped to SDR by mpv before
readback at full rate with unchanged copy costs. RESULTS.md carries the
tables and HDR-clip repro commands.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* spike(embedded-mpv): record 10-minute 4K60 HEVC long-run results
Zero dropped frames and zero torn reads after the first-minute warmup over
~8.5 minutes; steady-state late frames (~0.4%) track the 12 s test clip's
--loop restarts, not the copy pipeline.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* spike(embedded-mpv): viewport-scaling measurement + integration design draft
Confirms the render-at-viewport-size claim (4K source in a 720p FBO costs
720p: 0.17 ms readback / 0.16 ms copy / 0.17 ms upload at 60 fps) and adds
DESIGN.md — the draft integration architecture: per-session helper process
linking bundled libmpv on all platforms (finally full-featured + Wayland-
agnostic Linux), JSON-over-stdio control evolving the Linux wid protocol,
unchanged EmbeddedMpvSession renderer contract, shm generations for resize,
packaging via the existing vendored-runtime tooling, rollout behind its own
flag with the docked path as default.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* spike(embedded-mpv): auto-detect Homebrew prefix and Node headers for Intel Macs
BREW_PREFIX was hardcoded to /opt/homebrew (Apple Silicon) and NODE_INC to
one nvm version; both now resolve via brew --prefix and the PATH node's
execPath, so the pending Intel Mac run needs no Makefile edits. README gets
a fresh-machine checklist.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* spike(embedded-mpv): self-contained measurement bundle for machines without Node/pnpm
make-bundle.sh assembles a tarball with the spike sources, vendored N-API
headers (Makefile prefers them when present, so no Node install is needed),
pre-generated 4K HEVC/HDR10 test clips, and an official Electron dist
download for the target arch. collect-results.sh builds and runs the full
RESULTS.md scenario suite automatically (plus an optional --long 10-minute
run) and writes one results-<host>-<date>.txt to send back. Target-machine
prerequisites shrink to Xcode CLT + brew mpv — built for the pending Intel
Mac baseline run.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* spike(embedded-mpv): support MacPorts libmpv and legacy-macOS bundles
Makefile and collect-results.sh now detect libmpv in the Homebrew prefix or
MacPorts /opt/local (Homebrew is unsupported on legacy macOS like High
Sierra; 'sudo port install mpv +libmpv' provides libmpv there). make-bundle
takes ELECTRON_VERSION/BUNDLE_SUFFIX overrides — Electron 27+ needs macOS
10.15, so High Sierra bundles ship Electron 26.6.10 (LSMinimumSystemVersion
10.13).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* spike(embedded-mpv): scope macOS frame-copy engine to Apple Silicon only
Owner decision 2026-07-10: skip Intel Mac measurements and gate the future
frame-copy engine on arm64. Intel Macs able to run the app at all are a
shrinking 2015-2020 cohort and keep the docked/external/web player paths;
the macOS hardware gate closes with the M1 Pro numbers, and remaining
hardware risk moves to the Windows/Linux ports.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(embedded-mpv): frame-copy helper process and shm frame reader (native layer)
iptvnator_mpv_helper: one-process-per-session libmpv host that renders
offscreen at viewport size (headless CGL + async PBO ring, validated in
spikes/mpv-frame-copy), publishes BGRA frames into a seqlock shm ring with
resize generations, plays audio directly, and speaks a stdio protocol —
tab-separated commands in, JSON events out. The snapshot event mirrors
NativeEmbeddedMpvSessionSnapshot; status semantics (END_FILE reasons,
eof-reached with keep-open, pause gated on loaded path, fatal-only status
flips) are ported from embedded_mpv.mm.
embedded_mpv_frame_reader.node: plain-C N-API reader the preload script
uses to memcpy the newest complete frame into a V8 ArrayBuffer (Electron's
memory cage forbids zero-copy). Stub exports off macOS.
Both build as extra binding.gyp targets through build-embedded-mpv.js; the
helper gets the same libmpv dependency-path rewrite + ad-hoc re-sign as the
addon and is validated by the forbidden-link check.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(embedded-mpv): frame-copy engine wiring in main process and preload
EmbeddedMpvFrameCopyAdapter implements the NativeEmbeddedMpvAddon surface
over a per-session helper process (spawn, stdio protocol, snapshot cache,
graceful quit->SIGTERM->SIGKILL teardown), so EmbeddedMpvNativeService
reuses its polling/diff/power-blocker/recording logic unchanged. The
IPTVNATOR_ENABLE_EMBEDDED_MPV_FRAME_COPY flag (darwin/arm64 only) routes
getAddon() to the adapter and reports engine: 'frame-copy' in support.
The preload frame pump loads the shm reader addon, copies the newest frame
once per rAF into a reused buffer, and uploads it to WebGL2 on the
renderer's canvas — no frame data crosses the contextBridge; the bridge
only gains attachEmbeddedMpvFrameView/detachEmbeddedMpvFrameView. The
experiment flag relaxes the window sandbox for that native require;
contextIsolation and nodeIntegration:false stay on.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(embedded-mpv): frame-copy canvas mode in the player component + docs
EmbeddedMpvPlayerComponent renders <canvas data-embedded-mpv-frame> when
support reports engine 'frame-copy' and the session controller starts/stops
the preload frame pump around the session lifecycle. The bounds provider
skips HIDDEN_BOUNDS and the popover cutout for this engine — the canvas is
ordinary DOM, dialogs and popovers stack above it natively; bounds sync
still drives the helper's render size. Adapter unit tests cover spawn args,
snapshot caching, shm generations, protocol encoding, unexpected-exit
mapping, and dispose escalation. Architecture doc and CLAUDE.md describe
the engine, its flag, and the sandbox trade-off.
Verified end to end in the built app (M1 Pro): engine detection, helper
spawn, lavfi playback onto the canvas via CDP-injected smoke — including an
orientation fix (helper FLIP_Y already yields texture-order rows; the pump
shader must not flip uv again).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(embedded-mpv): close helper stdin on dispose + lifecycle logging
Live testing surfaced a stray idle helper that survived a session switch;
until the root cause is pinned down, dispose now also closes the child's
stdin (the helper exits on EOF) as a second kill path besides quit ->
SIGTERM -> SIGKILL, and spawn/dispose/exit are logged with the session id
so leaks are attributable.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(embedded-mpv): reap sessions when the renderer reloads or crashes
Root cause of the stray idle helper found during live testing: session
teardown lives in the renderer's Angular lifecycle, which never runs on a
renderer crash or hard reload — the main process kept the session (and its
frame-copy helper process / native mpv handle) alive until app shutdown.
EmbeddedMpvNativeService now watches the main window's webContents for
render-process-gone and did-navigate (full reloads only; in-app Angular
routing emits did-navigate-in-page) and disposes every session. Applies to
both engines. Verified live: location.reload() during frame-copy playback
logs 'Disposing 1 session(s): renderer reloaded' and the helper exits
cleanly. Regression test drives both events against the service.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(embedded-mpv): Settings toggle for the frame-copy engine
New 'Embedded MPV: frame-copy engine' checkbox in Settings > Playback,
shown only when the machine can run it (macOS arm64 with the helper binary
present — support now reports frameCopyAvailable). The choice persists to
the main-process config store because the engine relaxes the window sandbox
for the preload frame pump, which is fixed at window creation: main.ts
reads the store before creating the window and sets the engine env var; an
explicitly set env var (including '0') always wins, and the UI shows a
restart hint while the saved choice differs from the active engine.
Localized in all 18 locales.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(embedded-mpv): aspect-fit rendering in the frame-copy helper
The helper now observes dwidth/dheight and renders its FBO at the
aspect-fit size of the video inside the requested viewport, bumping a shm
generation on change — letterbox bars are never baked into frames (the VOD
watch shell's ~2:1 box no longer shows black side bars; the canvas
background is transparent so the sides show the app surface, while
fullscreen keeps its black backdrop). Frames also get smaller than the
viewport when aspects differ, trimming copy cost. Aspect override changes
refit automatically. Snapshots now carry videoWidth/videoHeight, and the
adapter forwards IPTVNATOR_EMBEDDED_MPV_AUDIO_DELAY to mpv's audio-delay
for lip-sync tuning until proper calibration lands.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(embedded-mpv): require frame-copy artifacts in macOS package validation + docs
macOS packages that ship embedded_mpv.node must also ship the
iptvnator_mpv_helper binary and the embedded_mpv_frame_reader.node addon —
they come out of the same binding.gyp run, and a package missing them would
silently lose the frame-copy engine. Covered in the package-identity test.
Architecture doc and CLAUDE.md document the Settings toggle, aspect-fit
rendering, audio-delay passthrough, and the renderer-reload session reaping.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(electron): inline TS helpers so the sandboxed preload keeps working
The frame pump's async/await (target es2015 + importHelpers) made webpack
externalize tslib in main.preload.js. Sandboxed preloads can only require
Electron's built-in module whitelist, so the entire preload script failed
to load and window.electron disappeared for every run without the
frame-copy flag. importHelpers:false for electron-backend keeps the preload
bundle self-contained — and future async code in preload can no longer
silently reintroduce the breakage. Verified live: sandboxed run now has the
bridge, reports engine 'native' and frameCopyAvailable true.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(embedded-mpv): commit the frame-copy analysis handoff + source inventory
The 2026-07-10 analysis that led to this branch now lives next to the spike
(spikes/mpv-frame-copy/ANALYSIS.md), and the architecture doc's What To
Commit section lists the frame-copy engine sources.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(embedded-mpv): address review findings on the frame-copy engine
- Stale pump attach can no longer win over a newer session: attach/detach
bump a shared epoch and async attach waits re-check it after every await,
so an attach for a replaced session aborts instead of installing itself
(greptile P1).
- A failed frame-view attach (no canvas, no WebGL2, reader missing) now
disposes the session and surfaces the error UI instead of leaving audio
playing behind a black canvas (codex P2).
- A stale frame-copy opt-in without the helper binary falls back to the
native engine instead of reporting embedded MPV unsupported, and the
Settings checkbox stays visible while a saved opt-in exists so it can
always be cleared (codex P2). Regression test covers the fallback.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(packaging): make the darwin frame-copy packaging test host-agnostic
On non-macOS CI hosts validatePackagedEmbeddedMpv also reports that macOS
link validation needs a macOS host, so the success-path assertion now
checks only the frame-copy artifact requirement instead of expecting an
empty error list.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(embedded-mpv): Windows/Linux porting handoff for the frame-copy engine
Self-contained entry point for porting sessions on other machines: current
state and coordination constraints, per-OS task lists (Linux EGL first,
then Windows WGL + named shm — the decisive iGPU perf gate), the
hard-won gotchas from the macOS integration (preload/tslib sandbox
breakage, V8 memory cage, frame orientation, stale-attach epoch, dispose
escalation, node-gyp naming, snapshot protocol semantics), testing
recipes, and the suggested milestone order.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(embedded-mpv): branching and merge strategy in the porting handoff
Port work goes to stacked branches off the frame-copy branch (PR base =
frame-copy branch, sequential merges, stack depth one), never into the
frozen PR #1169 branch itself.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(embedded-mpv): drop stale uncommitted note from porting handoff
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(embedded-mpv): harden frame-copy helper startup
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(playback): harden embedded mpv session handling and support detection
- guard the session controller against late startup rejections clobbering
a newer session during fast channel zapping
- exclude the refresh timestamp from the session-update dedup key so idle
sessions stop re-emitting IPC updates every 500 ms
- macOS: reconcile async loadfile replies by request id so a rejected
seek/aid/speed on a live stream no longer flips the session to error
- append --ozone-platform=x11 on Linux in main.ts so direct binary and
AppImage launches match the packaged .desktop launcher behavior
- return a sandbox-specific unsupported reason in Flatpak/Snap instead of
asking the user to install mpv inside the sandbox
- update the stale "macOS only" embedded MPV claim in CLAUDE.md
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(playback): populate Linux audio tracks and fix ARM Linux packaging
- Linux poller now reads track-list/count each tick and walks the scalar
track-list/N/* sub-properties when the count changes, so the audio-track
menu is no longer empty; selection reconciles from the aid property
- afterPack replaces the x64 embedded_mpv.node with an
embedded-mpv-unavailable.txt marker in arm64/armv7l Linux packages, and
package-layout verification rejects foreign-architecture addons while
requiring the marker
- extend native source invariants for the non-fatal async-reply rule
(macOS) and the Linux track-list polling contract
- document the Linux track-list mechanics and ARM packaging behavior in
docs/architecture/embedded-mpv-native.md
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(playback): embedded mpv player UX polish and full localization
- click on the video toggles pause (same action as Space) with a 250 ms
grace period so double-click fullscreen cancels the pending pause; no
DOM overlay is drawn — the dock transport icon is the feedback
- timeline scrubbing previews the drag position locally and commits a
single seek on release instead of one IPC seek per drag pixel
- translate all player UI strings (controls, tooltips, aria-labels,
status and recording messages) via new EMBEDDED_MPV.PLAYER.* keys,
synced across en + 17 locales through the i18n-fill workflow
- replace the legacy @Output() EventEmitter with the signal output() API
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(playback): react to language changes and respect ozone platform hint
Address review feedback on #1122:
- add a translationsTick signal (onLangChange/onTranslationChange/
onDefaultLangChange) read by every computed() and template helper that
calls translate.instant(), so labels re-evaluate on a runtime language
switch and when the translation file finishes loading after mount
- suppress the Linux --ozone-platform=x11 fallback when the user set
ELECTRON_OZONE_PLATFORM_HINT, matching the existing respect for an
explicit --ozone-platform switch
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(packaging): ship `ms` so the updater doesn't crash the app (#1103)
The 0.22 AppImage crashed on launch with "Cannot find module 'ms'" after
the desktop updater landed (b1119189). electron-updater requires
`debug` -> `ms` unguarded at startup, but the packaged app.asar shipped
`debug` without `ms`.
Root cause: with pnpm's isolated node-linker, electron-builder 26 uses its
PnpmNodeModulesCollector, which builds the bundle from `pnpm list --json`.
pnpm deduplicates repeated packages there, so all but one `debug@4.4.3`
occurrence report empty `dependencies` — and the collector (unlike the npm
collector) has no implicit-dependency recovery, so it drops `ms` entirely.
It stayed latent because the only prior `debug` consumer (follow-redirects
via axios) guards its require in try/catch; electron-updater is the first
packaged module to hit it unguarded.
Fix: declare `ms` as a direct dependency so it becomes a top-level,
fully-expanded node in the collector's tree and is bundled. This keeps the
isolated pnpm layout intact — `node-linker=hoisted` was rejected because it
removes `node_modules/.pnpm`, which apps/electron-backend/build-embedded-mpv.js
scans to resolve @electron/node-gyp, breaking the native build on every
platform.
Also add a packaged-asar dependency-closure guard to
verify-electron-package-layout.mjs: it audits every package shipped in the
archive and fails if any non-optional dependency is missing, so this class
of regression is caught in CI. Logic is extracted to a unit-tested module.
Verified locally: repackaged app.asar now ships `ms`, the embedded-mpv
native build succeeds, and the closure guard reports 0 missing.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(packaging): harden asar dependency-closure guard from review findings
Addresses review feedback on #1113 plus an adversarial-review finding:
- Walk every ancestor directory in resolvePackagedDependency (not just
node_modules boundaries) so a dependency hoisted to the archive root
resolves for packages under app subdirectories, matching Node's real
resolution (Codex review).
- Skip dependencies also declared in peerDependencies: host-provided
peers (e.g. electron) listed in both fields are not packaging defects
(Greptile review).
- Fix a silent no-op on Windows: @electron/asar lists entries and
resolves extractFile paths with the host separator, so the posix-only
matching audited zero packages on the Windows CI leg. Listings are now
normalized to posix and lookup paths converted back to the host
separator (pathSep is injectable for tests).
- Reject vacuous passes structurally: inspectPackagedDependencyClosure
now reports packageCount and manifestReadFailures, and the verifier
errors when the audit saw no packages or failed to read manifests,
so the guard can never silently audit nothing again.
Verified: 27 packaging tests pass; the real app.asar audits 235 packages
with 0 missing under both posix and simulated win32 IO; hiding `ms` from
a win32-shaped listing correctly flags it.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Adds experimental embedded MPV support for Windows and Linux, expands packaging/runtime validation, and updates CI coverage for the cross-platform native addon.
- Introduced tooling for building and staging the macOS `libmpv` runtime for IPTVnator's embedded MPV player.
- Added `build-macos-runtime.mjs` for building an LGPL-compatible runtime from source.
- Created `stage-macos-runtime.mjs` for staging the built runtime artifacts.
- Implemented validation for the packaged embedded MPV runtime in `electron-after-pack.cjs` and `embedded-mpv-macos.cjs`.
- Updated packaging scripts to ensure the embedded MPV runtime is correctly integrated and validated during the build process.
- Added README files to document the expected layout and usage for the embedded MPV runtime artifacts.
Entire-Checkpoint: c6e522b4276c
