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).
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:desktopBuild the default Electron Builder distribution target:
pnpm dist:desktopBoth 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:macosThe 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:packagedThe 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:packagedRequire the app-bundled FFmpeg path during smoke:
pnpm smoke:packaged:bundledRequire the packaged native CAMetalLayer preview helper during smoke:
pnpm smoke:packaged:native-previewRun both packaged release smokes:
pnpm smoke:packaged:releaseEvery 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.AppImageAn 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:devThe 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.
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.
- 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
- 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).
.deband Flatpak come after Beta. - Signing: unsigned (no Linux code-signing lane yet)
- AppImage runtime: the static type2-runtime (
toolsets.appimage: '1.0.2'inapps/desktop/electron-builder.yml). FUSE is linked in and it mounts throughfusermount3, so stock Ubuntu 24.04 needs nolibfuse2. - Chromium sandbox: an AppImage cannot carry a setuid
chrome-sandbox, so AppRun probesunshare -Ur trueand adds--no-sandboxonly where unprivileged user namespaces are refused (Ubuntu 24.04's AppArmor default). This is a backport of electron-builder #9590 inpatches/app-builder-lib@26.8.1.patch. Neither desktop entry passes the flag itself: the bundledvideorc.desktoprunsAppRun %U(theAppImageTargethunk of the same patch) and the entry the app writes forvideorc://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-appfails an AppImage whose bundled entry passes--no-sandbox. - FFmpeg: the SHA-256-pinned LGPL Linux x64 bundle fetched by
pnpm ffmpeg:fetch:linux, includingffmpeg,ffprobe, license, source-offer, and build-config metadata.libx264is forbidden. - Candidate workflow:
.github/workflows/release-linux-alpha.yml,workflow_dispatchfrom protectedmainonly - 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.jsoncarriesacceptanceStatus: waivedand the commit-pinned owner-waiver record URL; there is no promote workflow) - Updater feed filename:
latest-linux.ymlonly. 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.0and show "Videorc X is available. Download it from videorc.com" for the newest entry whoseplatformsincludelinuxand whose version is newer (apps/desktop/src/main/linux-update-notice.ts). Publishing a Linux release must therefore publish itslinuxchangelog 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/latestanswers 401 signed out), and points at the newest publishedrelease.jsonthroughVIDEORC_LINUX_DOWNLOAD_MANIFEST_OBJECT_KEY. Theupdates/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 withpnpm release:notify:discord <releaseId> --dry-runfirst, and never printVIDEORC_DISCORD_RELEASE_WEBHOOK.
Build a local AppImage with:
pnpm package:desktop:linuxPrepare 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:linuxStore 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:linuxNever reuse macOS Beta or Windows Alpha prefixes, latest-mac.yml, or
latest.yml.
- 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, includingffmpeg.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:
- every Windows local gate passing on Windows 11 x64;
- a strict, privacy-safe support bundle verification pass;
- valid Authenticode with the exact expected publisher and a trusted timestamp;
- manifest SHA-256 and byte size matching the downloaded installer;
- a current malware scan with no detections;
- clean-machine install, launch, recording, update, rollback, and uninstall evidence; and
- 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.
Unsigned local builds are useful for smoke testing only. The production release path is:
pnpm dist:desktop:signedSigned distribution first runs a redacted release preflight:
pnpm release:preflight:macosThe 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:macospnpm dist:desktop:signed also writes beta download metadata next to the DMG:
pnpm release:manifest:macosThe 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:macosThe 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 BuilderCSC_KEY_PASSWORD: certificate archive passwordAPPLE_ID: Apple Developer account emailAPPLE_APP_SPECIFIC_PASSWORD: app-specific password for notarizationAPPLE_TEAM_ID: Apple Developer Team IDVIDEORC_BUNDLED_TWITCH_CLIENT_ID: baked intovideorc-backendat compile timeVIDEORC_BUNDLED_KICK_CLIENT_ID: baked intovideorc-backendat compile timeVIDEORC_BUNDLED_KICK_CLIENT_SECRET: baked intovideorc-backendonly (neverapp.asar)VIDEORC_BUNDLED_X_OAUTH1_CONSUMER_KEY: allow-listed X app API key; Native X Live is dead without itVIDEORC_BUNDLED_X_OAUTH1_CONSUMER_SECRET: allow-listed X app API secret;release:validate:macosfails closed if either X half is missingVIDEORC_BUNDLED_YOUTUBE_CLIENT_ID: Google Desktop client ID, baked intovideorc-backendVIDEORC_BUNDLED_YOUTUBE_CLIENT_SECRET: Google Desktop client secret; Google refuses the token exchange without it even with PKCE, andrelease:validate:macosfails 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_IDVIDEORC_DOWNLOAD_S3_BUCKETVIDEORC_DOWNLOAD_S3_REGIONVIDEORC_DOWNLOAD_S3_SECRET_ACCESS_KEY
Conditional private download storage secrets:
VIDEORC_DOWNLOAD_S3_ENDPOINT_URL: required for Cloudflare R2 or other custom S3-compatible endpointsVIDEORC_DOWNLOAD_S3_FORCE_PATH_STYLE: usually true for path-style S3-compatible endpointsVIDEORC_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: secretsVIDEORC_RELEASE_UPLOAD_NEON_S3_ACCESS_KEY_ID,VIDEORC_RELEASE_UPLOAD_NEON_S3_SECRET_ACCESS_KEY; variablesVIDEORC_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: secretsVIDEORC_RELEASE_UPLOAD_HETZNER_S3_ACCESS_KEY_ID,VIDEORC_RELEASE_UPLOAD_HETZNER_S3_SECRET_ACCESS_KEY; variablesVIDEORC_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),hetznerorneon; 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:macosThe 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.jsonin private storage for investigation. - Cut a replacement beta such as
0.9.0-beta.2rather than mutating the rejected0.9.0-beta.1manifest.
If a beta has already been exposed on Videorc Web:
- Set
VIDEORC_DOWNLOAD_STORAGE_PROVIDER=noneand redeploy the web app withpnpm release:web:redeployto 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_KEYback to the last acceptedreleases/macos/<releaseId>/release.jsonand runpnpm release:web:redeploy. - Confirm anonymous requests still return
401, signed-in requests no longer receive the bad release URL, and/account/downloadshows 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.
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/*.dmgCopy 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-*.dmgInstall 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.appGrant 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-previewThen 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/.
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_FEATURESis downgrade-only:=0/basicforces 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_PUBKEYat 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).
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:backendWhere 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:windowsandrelease:preflight:linuxfail 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_IDis not mapped in CI: X OAuth 2.0 uses the public client id written intooauth.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_SECRETinstead (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/callbackis 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
localhostforms (Kick's docs uselocalhost), and the backend sendslocalhostfor 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_IDwhen building the backend. - Provide
VIDEORC_TWITCH_CLIENT_SECRETonly 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, anduser: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:strictThe 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.
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.jsonbeside 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 linevideorc-secrets:dpapi:1, followed by the blob.
Windows migration and recovery:
- A plaintext
videorc-secrets.jsonfrom 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
dpapibehaves 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-fileexplicitly; a plain JSON file handed to adpapibackend (as every smoke does today) is migrated on first read.
Startup maintenance, every platform with a file store:
- A
videorc-secrets.json.tmpleft 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 (thekick-flow,kick-flap,kick-relay-down, … fixture account ids). It records itself undermaintenance:test-fixture-purgeand matches whole refs only; real Kick account ids are numeric. The same pre-fix runs also replacedremote-control.lanandagents.registrywith 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.jsonVIDEORC_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 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 withVIDEORC_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.jsonWindows Alpha acceptance is stricter and must use:
pnpm support-bundle:verify -- <support-bundle.json> --windows-acceptanceThe 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.
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; bothffmpeg.exeandffprobe.exeplus 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:macosdownloads the official FFmpeg source archive and builds a per-architecture macOS executable.pnpm ffmpeg:fetch:windowsverifies the URL and SHA-256 invendor/ffmpeg/windows-pin.jsonbefore 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 -versionconfiguration contains--enable-gplor--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.
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.ymlfeed);dist:desktop:signedbelow is dmg-only. This checklist does not authorize a Windows Alpha. Windows uses the default-deny gate above and a datedwindows-app-acceptance-template.mdcopy.
pnpm installpnpm typecheckpnpm buildcargo fmt --check --allcargo testcargo clippy -- -D warningspnpm smoke:local-gatespnpm smoke:devpnpm smoke:oauthpnpm smoke:provider-readinesspnpm smoke:oauth-guardspnpm smoke:sourcespnpm smoke:start-labelspnpm smoke:streaming-secretspnpm smoke:platform-lifecyclepnpm smoke:screenspnpm smoke:multistreampnpm smoke:cohost-fakepnpm package:desktoppnpm smoke:packagedpnpm smoke:packaged:bundledpnpm 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-surfaceandpreviewSurfaceBacking = 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