Skip to content

DEPENDENCIES.md

Latest commit

 

History

History
127 lines (100 loc) · 5.08 KB

DEPENDENCIES.md

File metadata and controls

127 lines (100 loc) · 5.08 KB
Raw

Dependency integration

Videos delegates extraction and media processing to pinned yt-dlp, FFmpeg, and Deno executables. Users never install or locate these tools.

Bundle contract

The Xcode target embeds the following executable regular files:

Videos.app/
  Contents/
    MacOS/
      Videos
      Tools/
        yt-dlp
        ffmpeg
        libmp3lame.0.dylib
        deno

PBXCopyFilesBuildPhase uses the Executables destination, Tools subpath, and Code Sign On Copy for all four inputs from Vendor/MediaTools. The subsequent Sign yt-dlp Runtime phase applies Config/YTDLP.entitlements only to yt-dlp. The official standalone macOS artifact is built with PyInstaller and extracts its signed Python framework at runtime; without this helper-specific library-validation exception, Xcode's Hardened Runtime re-signing prevents that framework from loading. Sign FFmpeg Runtime similarly applies Config/FFmpeg.entitlements only to FFmpeg so the ad-hoc-signed helper can load its adjacent dynamic LGPL LAME library. The Swift application keeps library validation enabled. DependencyResolver checks the executable-relative location before resource fallbacks. This works from an installed app without relying on a shell PATH.

Legacy custom yt-dlp and FFmpeg bookmarks remain in AppSettings only so older settings data decodes safely. Normal app builds do not execute those files; only the signed bundled copies are eligible and no binary picker is exposed.

Pinned artifacts

Exact versions, URLs, source checksums, final universal checksums, and architectures are machine-readable in Vendor/MediaTools/manifest.json. Current pins:

  • yt-dlp nightly 2026.07.21.234255 official standalone universal macOS executable
  • FFmpeg 8.1.2 built from pinned official source with GPL, version-3, and nonfree components disabled
  • LAME 3.100 built as a dynamic encoder-only LGPL library
  • Deno 2.8.1 official arm64 and x86_64 builds combined with lipo

Deno is included because current yt-dlp YouTube extraction uses an external JavaScript runtime. The official yt-dlp executable includes its EJS scripts; the app supplies its own Deno path with --js-runtimes, so remote component downloads are not enabled.

Reproducible update workflow

Run:

./Scripts/update-media-tools.sh

The script fails closed on a checksum mismatch. Updating a pin requires:

  1. review the upstream release and security notes;
  2. update URLs and source checksums in the script;
  3. download and combine the architectures;
  4. record new final checksums in the script and manifest;
  5. inspect file, lipo -info, otool -L, and source signatures;
  6. run unit tests and signed-app metadata/MP4/MP3/cancellation smoke tests;
  7. update complete third-party license and source-compliance materials;
  8. create the selected ad-hoc release, verify all nested signatures, and publish a new app with its matching checksums.

Never modify tools inside a signed app; doing so invalidates its signature.

Invocation safety

Metadata and download calls always include:

--ignore-config
--no-remote-components
--js-runtimes deno:/absolute/bundled/path
--no-playlist
-- URL

Downloads also receive --ffmpeg-location with the separately resolved FFmpeg path. Arguments are passed directly to Process as an array. URLs, filenames, and paths are never interpolated into a shell command.

For a YouTube download-time HTTP 403, the service performs one automatic retry with the web_safari player client, its HLS formats, and IPv4. yt-dlp’s current PO-token guide identifies that client’s HLS formats as the no-token compatibility path. The app does not acquire browser cookies or generate proof tokens.

Deno receives a writable cache through DENO_DIR under the user cache directory, and DENO_NO_UPDATE_CHECK=1 prevents its own update check. The pinned yt-dlp implementation invokes it with no remote modules, no npm, a cache-only module policy, and no Deno permissions. Child processes receive only a small environment allowlist plus explicit app values, so unrelated parent-process secrets are not inherited. No component writes into the signed app.

Diagnostics

Advanced Settings shows yt-dlp, FFmpeg, and Deno status/version rows. Opening the app or Settings does not run version commands; inspection occurs only when the user selects Check Dependency Status, while each real operation still verifies that its required bundled executable exists. A missing tool indicates an incomplete or modified app bundle. The recovery path is to reinstall a complete app, not ask the user to find an executable.

Licensing

Preserve yt-dlp, FFmpeg, LAME, Deno, and transitive notices. The selected FFmpeg build reports LGPL-2.1-or-later and dynamically links the encoder-only LGPL LAME library. Its exact source, patch, build configuration, hashes, and reproduction script are retained.

See LEGAL_AUDIT.md, SOURCE_OFFER.md, SBOM.json, ThirdPartyLicenses/, and FFmpeg’s legal checklist. Publish the matching source-compliance package beside each final release. Obtain qualified advice for legal conclusions; these files are engineering evidence.