Skip to content

Latest commit

 

History

History
917 lines (735 loc) · 46.6 KB

distribution.md

File metadata and controls

917 lines (735 loc) · 46.6 KB

Videorc Distribution Notes

Current release policy:

Platform Track Public artifact policy
macOS 13+ Apple Silicon Beta Publish only the signed, notarized, stapled DMG after the macOS clean-machine gate.
Windows 11 x64 Alpha Default deny. Publish only a signed installer whose exact publisher and timestamp, digest and byte size, malware scan, real-device acceptance, update feed, and uninstall evidence all pass.
Linux x64 (AppImage) Alpha Public, owner-waived. The candidate workflow stores a private unsigned AppImage; the release owner publishes releases/linux-alpha/<releaseId>/release.json with a commit-pinned owner-waiver record and the signed-in videorc.com download serves it. No promote workflow, no updater feed, no physical acceptance yet. Beta needs both.

Hosted CI and local unsigned packages are engineering evidence, not public Windows or Linux Alpha releases. Keep the Windows download unavailable when any required gate is missing, failed, or blocked. A Linux Alpha is published only with an exact-candidate owner-waiver record (docs/acceptance/linux-alpha/); a failed or missing candidate validation still blocks it. Linux moves from Alpha to Beta only with physical acceptance on both Tier 1 boxes and no waiver (plan 257, D11).

Local Packaging

The unqualified packaging commands in this section describe the macOS path. Use windows-dev-loop.md and acceptance/windows-app-acceptance-template.md for Windows development and release-candidate evidence.

Build a packaged app directory with the Rust backend included as an extra resource:

pnpm package:desktop

Build the default Electron Builder distribution target:

pnpm dist:desktop

Both commands first run the backend/helper release build and stage the macOS FFmpeg bundle:

cargo build --release -p videorc-backend --bin videorc-backend --bin native_preview_host_helper
pnpm ffmpeg:build:macos
pnpm package:preflight:macos

The packaged Electron main process launches videorc-backend from process.resourcesPath, while development still runs the backend through Cargo. Packaged builds also bundle native_preview_host_helper at Resources/native_preview_host_helper so the production CAMetalLayer preview path can run without Cargo. Packaged builds prepend Resources/ffmpeg/bin to PATH and pass VIDEORC_BUNDLED_FFMPEG_PATH to the backend so the default FFmpeg path is the bundled executable. The same bundle includes sibling ffprobe, which the repair and recording analyzers derive from the bundled ffmpeg path. A custom FFmpeg path in Settings still overrides that default.

Run the packaged-app recording smoke test after pnpm package:desktop:

pnpm smoke:packaged

The smoke script launches the packaged .app, waits for the packaged backend to emit READY, calls the authenticated backend WebSocket, records a short local MKV test pattern through FFmpeg, stops the session, and verifies the file exists.

Useful overrides:

VIDEORC_PACKAGED_APP_EXECUTABLE=/path/to/Videorc.app/Contents/MacOS/Videorc pnpm smoke:packaged
VIDEORC_SMOKE_FFMPEG_PATH=/opt/homebrew/bin/ffmpeg pnpm smoke:packaged
VIDEORC_SMOKE_OUTPUT_DIR=/tmp/videorc-smoke pnpm smoke:packaged

Require the app-bundled FFmpeg path during smoke:

pnpm smoke:packaged:bundled

Require the packaged native CAMetalLayer preview helper during smoke:

pnpm smoke:packaged:native-preview

Run both packaged release smokes:

pnpm smoke:packaged:release

Packaged hardening (fuses and test hooks)

Every packaged build flips four Electron fuses before signing (electronFuses in apps/desktop/electron-builder.yml): ELECTRON_RUN_AS_NODE, NODE_OPTIONS, --inspect and the SIGUSR1 inspector are off, and app code loads only from app.asar. A release build also ignores VIDEORC_REMOTE_DEBUG_PORT, --remote-debugging-port/--remote-debugging-pipe, the native preview module/helper path overrides (VIDEORC_NATIVE_PREVIEW_HOST_MODULE, VIDEORC_NATIVE_PREVIEW_IN_PROCESS_MODULE, VIDEORC_NATIVE_PREVIEW_HOST_HELPER) and the talk-show smoke's fake camera and microphone (VIDEORC_SMOKE_FAKE_MEDIA_VIDEO, VIDEORC_SMOKE_FAKE_MEDIA_AUDIO and Chromium's --use-fake-device-for-media-stream family), and logs one Release build ignored test-only hooks line. Each of those lets another same-user process run code as Videorc, inheriting its Screen Recording, Camera and Microphone grants on macOS.

Check an artifact:

pnpm check:packaged-app                      # default release/ path for this OS
pnpm check:packaged-app --app /path/to/Videorc.app
pnpm check:packaged-app --app /path/to/Videorc-<version>-linux-x64.AppImage

An AppImage keeps the Electron binary inside its squashfs, so the check has the AppImage's own runtime extract the binary and app.asar to a temporary folder (without starting the app) and reads those.

A harness that needs CDP in a packaged app (the live lab, smoke:windows-main-window-recovery, perf probes against a packaged build) needs a packaged test build: set VIDEORC_PACKAGED_TEST_HOOKS=1 when electron-vite build runs (pnpm --filter @videorc/desktop package:linux:test-hooks, VIDEORC_PACKAGED_TEST_HOOKS=1 pnpm package:desktop, or $env:VIDEORC_PACKAGED_TEST_HOOKS='1' before pnpm package:desktop:windows). The fuses stay flipped. pnpm check:packaged-app refuses such a build unless you pass --allow-test-hooks; it must never ship. The packaged smoke command server (VIDEORC_PACKAGED_SMOKE_TEST, used by smoke:packaged* against the exact release payload) is unchanged.

pnpm smoke:windows-main-window-recovery prepares that separate test package automatically from the current source and existing compiled backend/FFmpeg. Set VIDEORC_PERF_APP_EXECUTABLE to the original production executable. The runner checks its hardening, builds a temporary directory with CDP enabled, checks the test package's fuses, runs recovery there, and verifies that the original executable and app.asar hashes did not change. Its report identifies the result as test-build evidence. The original installer and its recording checks remain production-build evidence; the recovery test package never ships.

For development acceptance, run the same backend recording smoke through pnpm dev:

pnpm smoke:dev

The development smoke test opens the Electron app through electron-vite, waits for the Electron main process to launch the Rust backend, records a short test-pattern MKV, stops the session, and verifies the output file. It intentionally avoids camera, microphone, and screen sources so it can validate app boot and recording control flow even before macOS permissions are granted.

Bundled microphone denoiser

The Rust backend links the pinned rnnoise-rs implementation and its embedded float model. Cargo fetches the pinned source during the build; the running app does not download a model or load a C RNNoise library. Shared Electron resources include licenses/rnnoise-rs/LICENSE.txt, UPSTREAM-NOTICES.txt and SOURCE.txt on every platform. Keep these notices with the backend binary when distributing it separately. See RNNoise for the source pin, model digest and capture-path restrictions.

Current macOS Beta Target

  • Packaging tool: Electron Builder
  • App id: dev.theorcdev.videorc
  • Product name: Videorc
  • Primary local target: unsigned macOS app directory
  • Local DMG target: unsigned
  • Production DMG target: signed and notarized when release secrets are present
  • App icon: generated from the current Videorc logo
  • FFmpeg: bundled LGPL-compatible executable for packaged macOS builds, with Settings override preserved

Current Linux Alpha Target

  • Packaging tool: Electron Builder
  • Supported target: x64 AppImage only, built on Ubuntu 24.04. The supported desktops are the Tier table in linux-port-plan.md (Ubuntu 24.04 GNOME, Arch/Omarchy Hyprland and Fedora KDE on Wayland are Tier 1; other desktops are best effort). .deb and Flatpak come after Beta.
  • Signing: unsigned (no Linux code-signing lane yet)
  • AppImage runtime: the static type2-runtime (toolsets.appimage: '1.0.2' in apps/desktop/electron-builder.yml). FUSE is linked in and it mounts through fusermount3, so stock Ubuntu 24.04 needs no libfuse2.
  • Chromium sandbox: an AppImage cannot carry a setuid chrome-sandbox, so AppRun probes unshare -Ur true and adds --no-sandbox only where unprivileged user namespaces are refused (Ubuntu 24.04's AppArmor default). This is a backport of electron-builder #9590 in patches/app-builder-lib@26.8.1.patch. Neither desktop entry passes the flag itself: the bundled videorc.desktop runs AppRun %U (the AppImageTarget hunk of the same patch) and the entry the app writes for videorc:// links runs the AppImage with %U (apps/desktop/src/main/linux-desktop-entry.ts), so a launch from the menu or a link gets the same probe. pnpm check:packaged-app fails an AppImage whose bundled entry passes --no-sandbox.
  • FFmpeg: the SHA-256-pinned LGPL Linux x64 bundle fetched by pnpm ffmpeg:fetch:linux, including ffmpeg, ffprobe, license, source-offer, and build-config metadata. libx264 is forbidden.
  • Candidate workflow: .github/workflows/release-linux-alpha.yml, workflow_dispatch from protected main only
  • Private storage prefix: candidates/linux-alpha/<releaseId>/<sourceCommit>/
  • Public prefix: releases/linux-alpha/<releaseId>/, written create-only by the release owner after the candidate passes validation (release.json carries acceptanceStatus: waived and the commit-pinned owner-waiver record URL; there is no promote workflow)
  • Updater feed filename: latest-linux.yml only. It is not published, so Linux does not self-update yet (plan 257 D4 adds AppImage updates)
  • In-app update notice: Linux builds never run electron-updater. They read the public https://www.videorc.com/api/changelog?since=<core>-alpha.0 and show "Videorc X is available. Download it from videorc.com" for the newest entry whose platforms include linux and whose version is newer (apps/desktop/src/main/linux-update-notice.ts). Publishing a Linux release must therefore publish its linux changelog entry; until the changelog lists the running Linux line, Settings says nothing about being up to date.
  • Public download: the videorc-web Linux download is live, signed-in (/api/downloads/linux/latest answers 401 signed out), and points at the newest published release.json through VIDEORC_LINUX_DOWNLOAD_MANIFEST_OBJECT_KEY. The updates/linux-alpha/ updater pointers stay unpublished until the Beta promote workflow and self-update exist. Send the Linux Discord announcement once that release is public; preview with pnpm release:notify:discord <releaseId> --dry-run first, and never print VIDEORC_DISCORD_RELEASE_WEBHOOK.

Build a local AppImage with:

pnpm package:desktop:linux

Prepare candidate metadata after packaging:

VIDEORC_RELEASE_ID=<version>-alpha.N \
VIDEORC_RELEASE_SOURCE_COMMIT=<40-character-sha> \
pnpm release:preflight:linux && pnpm release:manifest:linux && pnpm release:validate:linux

Store the private candidate (does not publish it; the owner publishes the public release.json as a separate step):

pnpm release:secrets:linux && pnpm release:candidate:upload:linux

Never reuse macOS Beta or Windows Alpha prefixes, latest-mac.yml, or latest.yml.

Current Windows Alpha Target

  • Packaging tool: Electron Builder
  • Supported release target: Windows 11 x64 only
  • Installer target: NSIS
  • Local/CI artifacts: may be unsigned and must remain internal
  • Public Alpha artifact: Authenticode-signed, timestamped, and matched against the exact pinned publisher identity
  • Preview: the uncompressed Electron proof surface documented in windows-port-plan.md, not macOS CAMetalLayer parity
  • FFmpeg: the SHA-256-pinned LGPL Windows x64 bundle fetched by pnpm ffmpeg:fetch:windows, including ffmpeg.exe, ffprobe.exe, license, and source-offer metadata

pnpm smoke:local-gates:windows is the maintained real-machine gate. Its final step runs the strict support-bundle verifier with --windows-acceptance; a missing physical microphone is a recorded BLOCKED result, not a synthetic pass. Copy the acceptance template to a dated note and record the installer publisher/timestamp, manifest and locally observed SHA-256/size, Microsoft Defender result, clean-profile install, feed/update, rollback, and uninstall evidence.

Do not publish or announce a Windows installer merely because the hosted windows.yml installer job succeeds. Publication additionally requires:

  1. every Windows local gate passing on Windows 11 x64;
  2. a strict, privacy-safe support bundle verification pass;
  3. valid Authenticode with the exact expected publisher and a trusted timestamp;
  4. manifest SHA-256 and byte size matching the downloaded installer;
  5. a current malware scan with no detections;
  6. clean-machine install, launch, recording, update, rollback, and uninstall evidence; and
  7. an accepted dated record referenced by the release manifest and public known issues page.

Any FAIL or BLOCKED result keeps Windows Alpha unavailable. Never replace an accepted installer in place; cut a new Alpha identifier and preserve the failed candidate for private investigation.

Support operators use the response and label matrix in support/windows-alpha-triage.md. Public issue reports use the repository's Windows Alpha form; raw support bundles move only through a maintainer-provided private channel after strict verification.

macOS Signing And Notarization

Unsigned local builds are useful for smoke testing only. The production release path is:

pnpm dist:desktop:signed

Signed distribution first runs a redacted release preflight:

pnpm release:preflight:macos

The preflight checks the signing/notarization environment variable names, codesign, spctl, xcrun notarytool, xcrun stapler, the macOS entitlement plist, and the writable release output directory. It reports only present/missing status for credential variables; it must not print credential values.

After pnpm dist:desktop:signed produces release artifacts, validate the latest .app and .dmg under apps/desktop/release:

pnpm release:validate:macos

pnpm dist:desktop:signed also writes beta download metadata next to the DMG:

pnpm release:manifest:macos

The manifest step writes release.json and Videorc-*.dmg.sha256, and refuses old product-name artifacts such as Videogre-*.dmg. Override VIDEORC_RELEASE_ARTIFACT to generate metadata for a copied candidate, or VIDEORC_RELEASE_ID, VIDEORC_RELEASE_DISPLAY_VERSION, and VIDEORC_RELEASE_NOTES_URL when cutting a later beta without changing the app bundle version.

Publish the signed DMG, checksum sidecar, and release.json to private S3-compatible download storage after validation:

pnpm release:upload:preflight:macos
pnpm release:upload:macos

The upload step uses the same server-only S3-compatible credentials as Videorc Web by default:

VIDEORC_DOWNLOAD_S3_ACCESS_KEY_ID=...
VIDEORC_DOWNLOAD_S3_BUCKET=...
VIDEORC_DOWNLOAD_S3_ENDPOINT_URL=... # optional, required for R2
VIDEORC_DOWNLOAD_S3_REGION=...
VIDEORC_DOWNLOAD_S3_SECRET_ACCESS_KEY=...

It uploads to releases/macos/<releaseId>/ unless VIDEORC_RELEASE_UPLOAD_PREFIX is set, and then verifies each object with a signed HEAD request. Use VIDEORC_RELEASE_UPLOAD_S3_* names to separate CI upload credentials from the web download signer, or VIDEORC_RELEASE_UPLOAD_SKIP_VERIFY=1 only when the storage provider does not support HEAD. The release workflow runs pnpm release:upload:preflight:macos before the expensive build and notarization steps so missing private-storage credentials fail early.

The validator runs codesign --verify, codesign -dv, Gatekeeper assessment via spctl, and xcrun stapler validate. It redacts repository and home-directory paths from command output. You can pass explicit artifact paths when validating a copied release candidate.

The GitHub Actions workflow at .github/workflows/ci.yml runs the same non-packaged local acceptance checks as pnpm smoke:local-gates for pushes to main and pull requests, split into named steps so hosted-runner failures identify the exact gate.

The release workflow at .github/workflows/release-macos.yml installs a smoke-test FFmpeg binary if the runner does not already provide one, runs the same local gates, runs pnpm dist:desktop:signed, then validates the signed artifacts with pnpm release:validate:macos for manual dispatches and v* tags. The smoke-test FFmpeg install is only for CI verification; packaged releases still use the bundled LGPL-compatible FFmpeg built by pnpm ffmpeg:build:macos.

Required GitHub secrets:

  • CSC_LINK: base64-encoded Developer ID Application certificate archive or a secure URL supported by Electron Builder
  • CSC_KEY_PASSWORD: certificate archive password
  • APPLE_ID: Apple Developer account email
  • APPLE_APP_SPECIFIC_PASSWORD: app-specific password for notarization
  • APPLE_TEAM_ID: Apple Developer Team ID
  • VIDEORC_BUNDLED_TWITCH_CLIENT_ID: baked into videorc-backend at compile time
  • VIDEORC_BUNDLED_KICK_CLIENT_ID: baked into videorc-backend at compile time
  • VIDEORC_BUNDLED_KICK_CLIENT_SECRET: baked into videorc-backend only (never app.asar)
  • VIDEORC_BUNDLED_X_OAUTH1_CONSUMER_KEY: allow-listed X app API key; Native X Live is dead without it
  • VIDEORC_BUNDLED_X_OAUTH1_CONSUMER_SECRET: allow-listed X app API secret; release:validate:macos fails closed if either X half is missing
  • VIDEORC_BUNDLED_YOUTUBE_CLIENT_ID: Google Desktop client ID, baked into videorc-backend
  • VIDEORC_BUNDLED_YOUTUBE_CLIENT_SECRET: Google Desktop client secret; Google refuses the token exchange without it even with PKCE, and release:validate:macos fails closed if either YouTube half is missing

A local keychain release reads the same bundled OAuth names from ~/.videorc-release.env (source export NAME= lines too). Do not invent placeholder values.

Required private download storage secrets:

  • VIDEORC_DOWNLOAD_S3_ACCESS_KEY_ID
  • VIDEORC_DOWNLOAD_S3_BUCKET
  • VIDEORC_DOWNLOAD_S3_REGION
  • VIDEORC_DOWNLOAD_S3_SECRET_ACCESS_KEY

Conditional private download storage secrets:

  • VIDEORC_DOWNLOAD_S3_ENDPOINT_URL: required for Cloudflare R2 or other custom S3-compatible endpoints
  • VIDEORC_DOWNLOAD_S3_FORCE_PATH_STYLE: usually true for path-style S3-compatible endpoints
  • VIDEORC_DOWNLOAD_S3_SESSION_TOKEN: required only for temporary credentials

Further release storage origins (publication goes to every configured origin; see "Storage origins" in releases/release-runbook.md). The target is Neon Object Storage as the single origin; Hetzner and R2 stay read-only until the soak ends, and VIDEORC_DOWNLOAD_STORAGE_PRIMARY=hetzner is the rollback:

  • neon: secrets VIDEORC_RELEASE_UPLOAD_NEON_S3_ACCESS_KEY_ID, VIDEORC_RELEASE_UPLOAD_NEON_S3_SECRET_ACCESS_KEY; variables VIDEORC_RELEASE_UPLOAD_NEON_S3_BUCKET, VIDEORC_RELEASE_UPLOAD_NEON_S3_REGION (e.g. eu-central-1), VIDEORC_RELEASE_UPLOAD_NEON_S3_ENDPOINT_URL (https://<branch-id>.storage.c-<N>.<region>.aws.neon.tech, host only)
  • hetzner: secrets VIDEORC_RELEASE_UPLOAD_HETZNER_S3_ACCESS_KEY_ID, VIDEORC_RELEASE_UPLOAD_HETZNER_S3_SECRET_ACCESS_KEY; variables VIDEORC_RELEASE_UPLOAD_HETZNER_S3_BUCKET, VIDEORC_RELEASE_UPLOAD_HETZNER_S3_REGION, VIDEORC_RELEASE_UPLOAD_HETZNER_S3_ENDPOINT_URL
  • variable VIDEORC_DOWNLOAD_STORAGE_PRIMARY: r2 (default), hetzner or neon; must match the videorc-web production environment and must name a configured origin (an unconfigured primary fails closed)

With only the neon values and VIDEORC_DOWNLOAD_STORAGE_PRIMARY=neon set, publication needs no VIDEORC_DOWNLOAD_S3_* values. The r2 names above stay required by pnpm release:secrets:macos while the D3 promotion still uses that slot.

Check the remote repository without printing secret values:

pnpm release:secrets:macos

macOS Beta Download Rollback

The web download route fails closed when no valid release manifest is available. Use that behavior for rollback instead of deleting release artifacts immediately.

If a beta fails before clean-machine acceptance:

  • Leave the production web environment pointed at the previous accepted manifest, or leave download storage disabled.
  • Keep the newly uploaded DMG, checksum sidecar, and release.json in private storage for investigation.
  • Cut a replacement beta such as 0.9.0-beta.2 rather than mutating the rejected 0.9.0-beta.1 manifest.

If a beta has already been exposed on Videorc Web:

  • Set VIDEORC_DOWNLOAD_STORAGE_PROVIDER=none and redeploy the web app with pnpm release:web:redeploy to stop issuing signed download URLs immediately. Never deploy a local videorc-web checkout (see "Redeploying videorc-web production" in releases/release-runbook.md).
  • Or change VIDEORC_DOWNLOAD_MANIFEST_OBJECT_KEY back to the last accepted releases/macos/<releaseId>/release.json and run pnpm release:web:redeploy.
  • Confirm anonymous requests still return 401, signed-in requests no longer receive the bad release URL, and /account/download shows the expected fallback or previous release metadata.

A distributable macOS build still needs:

  • Apple Developer account and Team ID
  • Developer ID Application certificate
  • Hardened runtime configuration
  • Entitlements review for screen, camera, microphone, and file access
  • Notarization credentials in CI or local release environment
  • Gatekeeper validation on a clean macOS account

Electron Builder's macOS docs describe hardened runtime, entitlements, and notarization requirements. Electron's code signing guide explains why distributed macOS apps need signing and notarization.

macOS Clean-Machine Release Candidate Checklist

Run this only with a signed and notarized release artifact. Use docs/acceptance/macos-release-candidate-template.md for the dated evidence note; do not treat this checklist itself as release evidence.

On the build machine:

pnpm smoke:local-gates
pnpm dist:desktop:signed
pnpm release:validate:macos
pnpm release:upload:macos
shasum -a 256 apps/desktop/release/*.dmg

Copy the signed DMG to a clean macOS user account or clean Mac. On that clean machine, validate the copied DMG before opening it:

spctl --assess --type open --context context:primary-signature --verbose /path/to/Videorc-*.dmg
xcrun stapler validate /path/to/Videorc-*.dmg
hdiutil attach /path/to/Videorc-*.dmg

Install or launch Videorc.app from the mounted image, then confirm Gatekeeper accepts the app without override:

spctl --assess --type execute --verbose /Applications/Videorc.app
xcrun stapler validate /Applications/Videorc.app
open /Applications/Videorc.app

Grant camera, microphone, and screen-recording permissions when prompted. If the clean machine has a repo checkout available for smoke scripts, run:

VIDEORC_PACKAGED_APP_EXECUTABLE="/Applications/Videorc.app/Contents/MacOS/Videorc" pnpm smoke:packaged:bundled
VIDEORC_PACKAGED_APP_EXECUTABLE="/Applications/Videorc.app/Contents/MacOS/Videorc" pnpm smoke:packaged:native-preview

Then perform one manual real-source recording from the packaged app:

  • screen source selected and visibly moving
  • camera source selected
  • microphone selected
  • native preview reports CAMetalLayer, with no production fallback to JPEG polling
  • local recording starts, stops, and plays back
  • no stream keys, OAuth tokens, local recordings, or generated media are committed

Record command output paths, screenshots, recording path, support bundle path if needed, failures, and final PASS/FAIL/BLOCKED verdict in a dated note under docs/acceptance/.

Open-Core Capability Boundary

Videorc's product boundary is open core: the local recording studio, its technical file-management tools, and livestreaming (including multistreaming and full streaming quality) remain a first-class free product, while cloud-assisted workflows and optional local creative transforms are premium capabilities. Multistreaming is free because the tee fan-out runs on the user's machine and costs Videorc nothing to serve (since 2026-09-15), and streaming quality is free for the same reason: the encode runs on the user's machine and the RTMP upload rides the user's own bandwidth (since 2026-09-28, Plan 075). This repository enforces the capability boundary; pricing and purchase flows belong to the product/website layer.

Capability Free/core Premium
Local recording Included: local MKV/MP4 recording remains first-class. Included.
Native preview Included: production preview uses the detached CAMetalLayer path when available. Included.
Source and layout controls Included: source selection, camera placement, presets, and local layout controls. Included.
Local library Included: session metadata, local files, remux, repair, and export helpers stay local. Included.
Local audio extraction Included when no cloud upload is requested. Included.
Local creative transforms Not included: optional content-enhancement transforms are separate from technical repair/export. Included: one-click on-device Noise Cleanup for finished recordings.
Livestreaming destinations Included: up to 5 destinations at full streaming quality (1080p60 / YouTube 4K30). Included.
Cloud AI workflow Not included in free/core. Included when the user grants cloud AI consent and required API credentials are present.

How the boundary is enforced (since 2026-07-05 there is no runtime unlock):

  • Release builds resolve to Basic unless the signed-in videorc.com account hydrates a verified premium entitlement. No environment variable can raise the tier — VIDEORC_PREMIUM_FEATURES is downgrade-only: =0/basic forces Basic (for exercising the gates), every other value is ignored with a warning. The tier changes cloud AI, live captions, Sidekick, and Noise Cleanup; the streaming quality ceiling and the destination cap are the same shared numbers for every tier and are pipeline limits, not plan gates.
  • The premium entitlement is a signed proof, not a boolean: videorc.com mints an Ed25519-signed token (7-day expiry) that the backend verifies against a compiled-in public key and persists locally, so a premium user who restarts offline keeps premium until the token expires. Release builds trust only the compiled-in key; dev builds may point VIDEORC_ENTITLEMENT_PUBKEY at a dev keypair for localhost web work.
  • Debug/dev builds resolve to the Developer tier automatically, which is what the smokes and baselines rely on; they must not depend on a real signed-in account.
  • Cloud AI is additionally server-bound: transcription, titles, chapters, and live-caption tokens are minted by videorc.com for premium accounts, so a patched client cannot reach them.

Local recording, native preview, source/layout controls, the library, local repair/remux/export, and local audio extraction without upload must not require premium entitlement. Optional creative transforms that change recording content, such as Noise Cleanup, may require Premium even when their media processing stays on-device. Anyone distributing a modified build must also follow TRADEMARK.md (rebrand, own bundle id, own OAuth clients, own feed/backend).

OAuth Client IDs

Production builds should inject Videorc-owned OAuth client IDs at backend compile time. Development and self-hosted builds can override those IDs at runtime.

Google approved YouTube OAuth (youtube.force-ssl) on 2026-09-30. There is no separate enable flag: a build that bakes both YouTube values offers YouTube sign-in, and one without them keeps YouTube on Manual RTMP.

Bundled production defaults:

VIDEORC_BUNDLED_TWITCH_CLIENT_ID=...
VIDEORC_BUNDLED_X_CLIENT_ID=...
# Kick (plan 063): id AND secret. Kick's token endpoint requires the secret
# even with PKCE, so Kick OAuth is dark unless both are baked in.
VIDEORC_BUNDLED_KICK_CLIENT_ID=...
VIDEORC_BUNDLED_KICK_CLIENT_SECRET=...
# YouTube: id AND secret. Google's Desktop client requires the secret in the
# token exchange even with PKCE.
VIDEORC_BUNDLED_YOUTUBE_CLIENT_ID=...
VIDEORC_BUNDLED_YOUTUBE_CLIENT_SECRET=...
pnpm package:backend

Where the bundled values come from:

  • macOS builds on the release Mac and reads them from ~/.videorc-release.env.
  • Windows and Linux alpha candidates build in GitHub Actions and read repository secrets with the same names (VIDEORC_BUNDLED_TWITCH_CLIENT_ID, VIDEORC_BUNDLED_KICK_CLIENT_ID, VIDEORC_BUNDLED_KICK_CLIENT_SECRET, VIDEORC_BUNDLED_X_OAUTH1_CONSUMER_KEY, VIDEORC_BUNDLED_X_OAUTH1_CONSUMER_SECRET, VIDEORC_BUNDLED_YOUTUBE_CLIENT_ID, VIDEORC_BUNDLED_YOUTUBE_CLIENT_SECRET). release:preflight:windows and release:preflight:linux fail closed when a required one is missing (scripts/lib/release-bundled-oauth.mjs). Until this check existed, every Windows alpha shipped with no Twitch, Kick or X Live sign-in: users saw "Twitch OAuth requires VIDEORC_TWITCH_CLIENT_ID." When a value rotates, update both the release env and the repository secret.
  • VIDEORC_BUNDLED_X_CLIENT_ID is not mapped in CI: X OAuth 2.0 uses the public client id written into oauth.rs, and an empty build variable counts as unset.

Runtime/self-host overrides:

VIDEORC_TWITCH_CLIENT_ID=...
VIDEORC_X_CLIENT_ID=...
VIDEORC_KICK_CLIENT_ID=...
VIDEORC_KICK_CLIENT_SECRET=...
VIDEORC_YOUTUBE_CLIENT_ID=...
VIDEORC_YOUTUBE_CLIENT_SECRET=...

Runtime values take precedence over bundled defaults. Kick and YouTube are the providers whose client secrets are baked into the backend binary (like the X OAuth 1.0a consumer pair below), because neither has a secretless flow. The release validator fails if VIDEORC_BUNDLED_KICK_CLIENT_SECRET appears in plain text in app.asar: it belongs to the Rust backend only. Other client secrets, when used for provider flows, remain runtime-only:

VIDEORC_TWITCH_CLIENT_SECRET=...
VIDEORC_X_CLIENT_SECRET=...

Native X Livestream source/broadcast management is not covered by the X OAuth2 PKCE token — it signs every request with OAuth 1.0a (consumer pair + per-user access token). The credential model has two halves:

  • Consumer pair (app-level): the allow-listed Videorc X app's API key and secret. Release builds bake them into the backend binary from ~/.videorc-release.env — the same mechanism as the bundled YouTube client secret:

    VIDEORC_BUNDLED_X_OAUTH1_CONSUMER_KEY=...
    VIDEORC_BUNDLED_X_OAUTH1_CONSUMER_SECRET=...
    pnpm package:backend

    Self-hosted builds without baked values set the runtime overrides VIDEORC_X_OAUTH1_CONSUMER_KEY / VIDEORC_X_OAUTH1_CONSUMER_SECRET instead (both or neither — a partial pair is a hard error).

  • User access token (per-user): minted in-app. The Streaming tab's Authorize X Live button runs the 3-legged OAuth 1.0a flow (request token → x.com approval in the browser → loopback callback → access token) and stores the token pair in the backend secret store (platform:x:oauth1:* refs). Disconnecting the X account deletes it. Smoke rigs and self-hosting can bypass the browser flow with the runtime-only env override (takes precedence over the stored token):

    VIDEORC_X_OAUTH1_ACCESS_TOKEN=...
    VIDEORC_X_OAUTH1_ACCESS_TOKEN_SECRET=...
    VIDEORC_X_OAUTH1_USER_ID=...   # optional; defaults to the token's numeric prefix

All of these values are secrets except the numeric user id. They must not be bundled into the renderer and must not appear in support bundles or logs; the backend surfaces only source labels (bundled, environment, user-authorized), never values. The OAuth 1.0a authorize flow uses the same loopback callback listener and registered callback URLs as OAuth2 (below).

OAuth callback URLs (all providers):

  • The backend binds a dedicated loopback listener for OAuth callbacks on the first free port of 17995, 27995, 37995. Register ALL THREE as callback URLs in each active OAuth provider's developer portal: http://127.0.0.1:17995/oauth/callback, http://127.0.0.1:27995/oauth/callback, http://127.0.0.1:37995/oauth/callback. Exact-match providers (X, Twitch) reject anything else.

  • videorc://oauth/callback is a legacy escape hatch for X only (VIDEORC_OAUTH_X_CALLBACK=app-protocol). Do not use it by default: X auto-approves re-authorization without a user gesture, and browsers block gestureless custom-scheme navigation, leaving the consent page on an infinite spinner.

  • Kick registers the localhost forms (Kick's docs use localhost), and the backend sends localhost for Kick as it does for Twitch: http://localhost:17995/oauth/callback, http://localhost:27995/oauth/callback, http://localhost:37995/oauth/callback.

Twitch release blocker:

  • Register a Videorc-owned Twitch developer app before a production release candidate.
  • Register the three fixed loopback callback URLs listed above.
  • Bundle the public app client ID with VIDEORC_BUNDLED_TWITCH_CLIENT_ID when building the backend.
  • Provide VIDEORC_TWITCH_CLIENT_SECRET only in the runtime or release-smoke environment. The current Twitch provider flow is not PKCE-only, so the app is not considered ready without the runtime secret.
  • Verify the app requests the scopes used by the backend: channel:manage:broadcast, channel:read:stream_key, and user:read:chat.

The backend exposes credential source status to the renderer as environment, bundled, or missing; it never exposes actual client ID or secret values. Before a public release, confirm the YouTube row reports bundled and opens the consent disclosure before Google OAuth.

Before a release candidate, run the redacted provider readiness check:

pnpm smoke:provider-readiness
pnpm smoke:provider-readiness:strict

The strict run requires active-provider OAuth client IDs, Twitch's optional runtime client secret when using a confidential Twitch app, eligible Twitch test accounts, and validated X Livestream OAuth1/API access. See OAuth Live Smoke Runbook for the full external acceptance workflow.

Credential Storage

Current release decision: stream keys and OAuth tokens use Videorc's explicit owner-only JSON credential store in both development and packaged macOS builds. The backend reports this as json-file in health diagnostics. A macOS Keychain backend is intentionally not the default in this build because unsigned/dev rebuilds repeatedly prompt for the login password and make local validation unstable.

On Windows the default is dpapi (#1078): the same JSON payload, at the same path, wrapped with CryptProtectData in user scope (no prompt, no UI). The signed-in Windows account is the boundary; the per-user %APPDATA% ACL alone left the account session, entitlement token, Phone remote device keys and the agents registry token readable as plain text.

Default location:

  • Development and packaged macOS: videorc-secrets.json beside the app's SQLite database in the per-user app-data directory.
  • Unix permissions: the file is written with mode 0600.
  • Windows: %APPDATA%\Videorc\videorc-secrets.json, DPAPI-protected. The file starts with the line videorc-secrets:dpapi:1, followed by the blob.

Windows migration and recovery:

  • A plaintext videorc-secrets.json from an older build is protected in place the first time the backend reads it (one atomic replace, so the plaintext copy never coexists with the protected one).
  • A file the signed-in account cannot decrypt (copied from another user or machine, or damaged) is never deleted or overwritten. Every secret access fails with the file's path in the error until the file is removed by hand (quit Videorc, delete it, sign in and re-pair) or opened by the account that wrote it.
  • Downgrading to a build without dpapi behaves the same way: the older build reports the file as "not valid JSON" on every access and writes nothing, so the protected store survives a round trip through an older version.
  • Smokes and self-hosting that read the file back can set VIDEORC_SECRET_STORE=json-file explicitly; a plain JSON file handed to a dpapi backend (as every smoke does today) is migrated on first read.

Startup maintenance, every platform with a file store:

  • A videorc-secrets.json.tmp left by a backend that died between staging the new file and renaming it over the store is removed once the store itself has loaded. A store that fails to load keeps its .tmp: after a crash it may be the only readable copy.
  • A one-time purge drops the Kick event-subscription entries that unit tests before 2026-11-01 (802acbe1) wrote into a developer's real store (the kick-flow, kick-flap, kick-relay-down, … fixture account ids). It records itself under maintenance:test-fixture-purge and matches whole refs only; real Kick account ids are numeric. The same pre-fix runs also replaced remote-control.lan and agents.registry with fixtures: if Phone remote or an agent pairing looks wrong on a developer machine, re-pair it.

Useful overrides:

VIDEORC_SECRET_STORE=json-file   # or dpapi (Windows builds only)
VIDEORC_SECRETS_PATH=/path/to/videorc-secrets.json

VIDEORC_SECRET_STORE=keychain is rejected in this build instead of silently falling back, and so is dpapi on a build without it. Revisit Keychain only after a signed identity can prove stable permissions without repeated prompts.

To delete local credentials, disconnect provider accounts in the Streaming tab and clear saved manual stream keys. For a full local reset, quit Videorc and delete videorc-secrets.json from the app-data directory shown beside the database path in Settings. Do not commit this file, logs that contain credential material, recordings used as secret evidence, or screenshots that show stream keys. Diagnostics and health payloads may include masked hints or backend kind; they must never include secret values.

Support Bundles

Support bundles are local, redacted JSON diagnostics files for manual testing and bug reports. They are generated from the Diagnostics tab with Support bundle -> Export. After export, the success toast can reveal the file in Finder.

Default location:

  • Development and packaged macOS: support-bundles/ beside the app's SQLite database, usually ~/Library/Application Support/Videorc/support-bundles/.
  • If the backend cannot derive a database parent directory, it falls back to the system temp directory under videorc-support-bundles/.

Filename format:

videorc-support-bundle-YYYYMMDD-HHMMSSZ.json

Included sections:

  • app version, commit when available, platform, and dev/packaged run mode
  • backend health and FFmpeg status
  • entitlement snapshot
  • current recording status
  • latest diagnostic stats
  • recent backend logs and health events
  • persisted backend crash records (rendererDiagnostics.runtimeInfo.backendCrashes, last 5, most recent first): exit code/signal, supervisor generation and restart attempt, uptime, and the dying process's last stderr lines — this is what explains a "Backend crashed, restarting" toast after the restart already happened
  • recent session summaries with media paths reduced to redacted basenames
  • redaction summary counters

Durable backend evidence outside the bundle (both under Electron's userData directory, ~/Library/Application Support/Videorc/ on macOS and %APPDATA%\Videorc\ on Windows):

  • backend-crashes.json — the crash records above, written atomically at the moment of each non-intentional backend exit (and intentional stops with a non-zero code).
  • logs/backend.log (+ backend.log.1, 2 × 2 MB rotation) — every backend stderr line and supervisor lifecycle line, so packaged builds without a terminal keep logs across restarts. A Rust panic writes one structured line, {"panic":…,"location":…,"thread":…}, before the default panic output; debug builds can force one at startup with VIDEORC_DEV_PANIC_ON_START=1.

pnpm smoke:backend-resilience kills the backend with SIGKILL and asserts the record, the log file, and runtimeInfo.backendCrashes all carry the crash.

Excluded by default:

  • local recordings, screenshots, extracted audio, and generated media evidence
  • SQLite database files and credential-store files
  • stream keys, OAuth tokens, API keys, client secrets, and URL credentials
  • raw home-directory paths when not needed
  • AI artifact bodies such as transcripts, summaries, chapters, and generated publish text

Before attaching a support bundle to a bug report, run:

pnpm support-bundle:verify /path/to/videorc-support-bundle-YYYYMMDD-HHMMSSZ.json

Windows Alpha acceptance is stricter and must use:

pnpm support-bundle:verify -- <support-bundle.json> --windows-acceptance

The verifier checks required sections and fails if secret-shaped values, raw database/media paths, unredacted RTMP URLs, or AI artifact bodies appear. Attach the JSON bundle only when that command passes and a maintainer provides a private transfer path. A GitHub issue is public: record only the verifier verdict there, not the bundle, its local path, recordings, screenshots, device IDs, or account details.

FFmpeg Strategy

Decision:

  • Development keeps FFmpeg external by default.
  • Packaged macOS builds bundle an LGPL-compatible FFmpeg executable and keep the custom FFmpeg path override in Settings.
  • Windows development and packaged candidates use the SHA-256-pinned LGPL x64 bundle fetched by pnpm ffmpeg:fetch:windows; both ffmpeg.exe and ffprobe.exe plus license/source metadata are required.

Rationale:

  • External FFmpeg is acceptable for source development, but neither public platform may require a user to install FFmpeg separately.
  • Public creator UX should not require Homebrew or manual FFmpeg repair before first recording.
  • Keeping a Settings override preserves debugging and power-user workflows.

Do not bundle a GPL or nonfree FFmpeg build unless the product/legal strategy explicitly changes.

Bundle source:

  • pnpm ffmpeg:build:macos downloads the official FFmpeg source archive and builds a per-architecture macOS executable.
  • pnpm ffmpeg:fetch:windows verifies the URL and SHA-256 in vendor/ffmpeg/windows-pin.json before staging the Windows x64 bundle.
  • The configure flags include --disable-gpl, --disable-nonfree, --enable-avfoundation, --enable-audiotoolbox, and --enable-videotoolbox.
  • The script refuses to stage a binary whose ffmpeg -version configuration contains --enable-gpl or --enable-nonfree.
  • The staged resource includes NOTICE.txt, SOURCE.txt, BUILD-CONFIG.txt, LGPL license texts, and the upstream license overview.
  • Generated FFmpeg binaries live under vendor/ffmpeg/current/ and are intentionally ignored by git.

The release process must make source for the exact FFmpeg archive available beside public Videorc binary downloads. See FFmpeg's legal checklist before changing configure flags or distribution strategy.

macOS Beta Release Checklist

For the per-release "bump version → build → publish → existing users auto-update" flow (including the electron-updater feed), follow releases/release-runbook.md. Note: an auto-update release uses pnpm dist:desktop:release (builds the dmg and the zip/latest-mac.yml feed); dist:desktop:signed below is dmg-only. This checklist does not authorize a Windows Alpha. Windows uses the default-deny gate above and a dated windows-app-acceptance-template.md copy.

  • pnpm install
  • pnpm typecheck
  • pnpm build
  • cargo fmt --check --all
  • cargo test
  • cargo clippy -- -D warnings
  • pnpm smoke:local-gates
  • pnpm smoke:dev
  • pnpm smoke:oauth
  • pnpm smoke:provider-readiness
  • pnpm smoke:oauth-guards
  • pnpm smoke:sources
  • pnpm smoke:start-labels
  • pnpm smoke:streaming-secrets
  • pnpm smoke:platform-lifecycle
  • pnpm smoke:screens
  • pnpm smoke:multistream
  • pnpm smoke:cohost-fake
  • pnpm package:desktop
  • pnpm smoke:packaged
  • pnpm smoke:packaged:bundled
  • pnpm smoke:packaged:native-preview
  • Build the backend with bundled OAuth client IDs for production release candidates
  • Launch the packaged app from apps/desktop/release/mac*/Videorc.app
  • Confirm the packaged backend emits READY
  • Confirm the packaged native preview smoke reports previewTransport = native-surface and previewSurfaceBacking = cametal-layer
  • Confirm Streaming tab OAuth credential source badges show bundled defaults or intended overrides
  • Complete the OAuth live smoke runbook for YouTube, Twitch, and X, or record X native live as release-blocking if OAuth1 credentials or allow-listed API access are not available
  • Confirm FFmpeg unavailable states are visible and non-crashing
  • Record a short MKV using the bundled FFmpeg path
  • Stop recording and confirm the session appears in Library