Eve library

@aphrodite/streaming

Other

Revision 1

On this page

@aphrodite/streaming — part of the Oshun monorepo.

TypeScript package. Built with tsc/tsup; consumed by other workspaces.

Scripts#

Command Definition
pnpm build tsup
pnpm dev tsx watch src/index.ts
pnpm start node dist/index.js
pnpm lint eslint src/
pnpm typecheck tsc --noEmit

Layout#

  • src/

Media-edge authentication and reconciliation#

MediaMTX publisher external auth posts to /api/ingest/rtmp/auth with its publisher grant as token (or password). The route accepts the canonical live-media.v1/aphrodite/<stream UUID> path only. Bare UUIDs and canonical sibling-tenant paths are rejected before publisher-grant lookup. The route name is retained for compatibility, but the contract authorizes MediaMTX RTMP, SRT, WebRTC, and RTSP publisher requests. A grant is accepted only for its exact stream and an active broadcaster.

Configure these values for every streaming-service deployment:

Variable Purpose
MEDIAMTX_HOOK_SECRET Separate shared secret required in X-Media-Hook-Key on lifecycle and manual-reconciliation callbacks.
MEDIAMTX_CONTROL_URL HTTP(S) base URL of the MediaMTX Control API, for example http://mediamtx:9997.
MEDIAMTX_EDGE_ID Stable, unique identity for this MediaMTX edge.
MEDIAMTX_RECONCILE_INTERVAL_MS Poll interval from 1,000 to 300,000 ms; defaults to 15,000.

Lifecycle callbacks post path, sourceType, and sourceId to /api/ingest/rtmp/on-publish and /api/ingest/rtmp/on-publish-done. They fail closed if the hook secret, edge identity, stream, or durable publisher-edge store is unavailable. MediaMTX external auth, lifecycle callbacks, edge reconciliation, recording RTSP sources, and publisher provisioning all use the same canonical tenant-scoped path. The separately shaped legacy streamId and RTMP app/name callback bodies remain compatibility inputs; they do not make bare UUID MediaMTX path values valid. Configure MediaMTX's Control API and the same edge ID as well: the service reconciles immediately at startup and periodically thereafter, recovering missed callbacks without overlapping polls. A provider failure is reported and retried; it is never interpreted as an empty edge.

Apply the Aphrodite database migrations before enabling the callbacks. Current publisher state is stored in the RLS-protected live_media_publisher_edge_sessions table and is retained across service restarts.

The real local edge gate requires Docker, FFmpeg, and ffprobe. It starts pinned MediaMTX and PostgreSQL images, rejects a forged SRT grant, publishes generated encoded media, probes decoded edge HLS, and runs the selected Neith/FFmpeg adapter against the same live RTSP source. It applies live-media migrations 00005–00010 plus the optional-provider ledgers in 00013–00016, drives the durable job through claim/restart/expired-lease recovery and fenced completion, packages the transcode into HLS and DASH, and publishes immutable local origin objects. The same edge issues a Veritas-fixed publisher grant only after registering v1.veritas-live in the forced-RLS PostgreSQL registry, authenticates canonical SRT publishing through a reconstructed SQL-backed control, decodes its HLS, and reauthenticates the persisted grant after database client/service reconstruction. The same generated rehearsal bytes become a durable Veritas HLS/DASH publication; tenant-fixed Veritas viewer and grant controls then issue signed protected playback through SQL authority. A V3 Stage tenant-fixed publisher control also registers the same stream UUID as v3.stage:<stream UUID> in its isolated forced-RLS scope, issues and authenticates a durable grant, rejects the Veritas secret while Veritas rejects the Stage secret, and revokes the Stage grant without publishing fictitious Stage content. A Playwright-driven Chromium run mounts the actual Rail first-party-live panel, decodes both protocols, persists positive QoE and presence, releases the lane, and proves the former token immediately receives VIEWER_SESSION_INACTIVE. A separate Aphrodite SQL entitlement decision joins a durable viewer lease and issues protected playback, whose manifest and segments are decoded as H.264/AAC. The gate reconstructs the database client, shared services, and disk origin; proves forced-RLS isolation, age-policy denial, idempotent refresh, multi-node presence, exact QoE persistence, crash expiry, token-fenced reconnect, explicit leave, and immediate session-bound origin denial; rejects missing/tampered credentials; invalidates playback on durable publication revocation; and reconciles publisher teardown. MediaMTX uses environment-only configuration from an empty working directory so the test does not consume a host configuration-file watcher. The same gate extracts a JPEG from a real published transport segment, persists privacy-bounded analysis evidence, replays it without a second provider call after database restart, fences concurrent and stale analysis workers, and proves cross-tenant denial. It also captures the live publisher through RTSP into a checksummed, FFprobe-verified MP4 object, replays that durable result without a second FFmpeg call, recovers and fences an abandoned recording lease, and denies a second tenant. Finally, it provisions a nonextractable RSA KEK in SoftHSM, protects the real HLS with AES-128, proves PostgreSQL contains only wrapped custody metadata, rejects unauthenticated key delivery, and decodes the authenticated protected H.264/AAC publication through FFprobe before restart replay and lease-fencing checks. Build the Neith runner first:

bash
cargo build --manifest-path ../../../libs/neith/stream-encoder/crates/neith-stream-encoder/Cargo.toml --bin neith-stream-transcoder
LIVE_MEDIA_EDGE_E2E=1 pnpm exec vitest run src/mediamtx-edge.e2e.spec.ts

Set LIVE_MEDIA_MEDIAMTX_IMAGE only when deliberately testing another MediaMTX build. Set LIVE_MEDIA_NEITH_TRANSCODER_BIN only when the runner was built at a non-default path; the default is libs/neith/target/debug/neith-stream-transcoder.

Durable transcode/publication jobs#

The internal job API is real and tenant-fixed:

Route Behavior
POST /api/transcoding Enqueue or replay an idempotent job.
GET /api/transcoding List durable jobs with bounded filters.
GET /api/transcoding/:jobId?streamId=<uuid> Read one stream-owned job.
DELETE /api/transcoding/:jobId?streamId=<uuid> Request cancellation or cancel due work.

All four routes require X-API-Key to equal the nonempty deployment INTERNAL_API_KEY; development mode never accepts an arbitrary presented key. The caller supplies a stream UUID, an idempotency key, and bounded media/rendition parameters. Tenant, job, attempt, execution, publication, and lease identities are generated inside the Aphrodite control boundary.

Set LIVE_MEDIA_PIPELINE_ENABLED=1 only after migration 00009 is applied and the following required values are configured:

Variable Purpose
LIVE_MEDIA_PIPELINE_WORKER_ID Stable identity for this worker process.
LIVE_MEDIA_NEITH_RUNNER_BINARY Absolute compiled Neith runner path.
LIVE_MEDIA_TRANSCODE_ROOT Absolute private transcode-output root.
LIVE_MEDIA_PACKAGE_ROOT Absolute private HLS/DASH packaging root.
LIVE_MEDIA_S3_BUCKET Create-only origin bucket.
LIVE_MEDIA_S3_REGION AWS/MinIO signing region.

Optional S3/MinIO settings are LIVE_MEDIA_S3_ENDPOINT, LIVE_MEDIA_S3_ACCESS_KEY_ID, LIVE_MEDIA_S3_SECRET_ACCESS_KEY, LIVE_MEDIA_S3_FORCE_PATH_STYLE, LIVE_MEDIA_S3_SERVER_SIDE_ENCRYPTION, and LIVE_MEDIA_S3_KMS_KEY_ID. Lease/retry bounds are configurable with LIVE_MEDIA_PIPELINE_LEASE_MS, LIVE_MEDIA_PIPELINE_RENEWAL_MS, LIVE_MEDIA_PIPELINE_INITIAL_RETRY_MS, LIVE_MEDIA_PIPELINE_MAXIMUM_RETRY_MS, and LIVE_MEDIA_PIPELINE_IDLE_INTERVAL_MS. Partial credentials, relative roots, unsafe bounds, and invalid encryption settings prevent startup.

Publication-bound content analysis#

The optional analysis API is available only when the durable pipeline runtime is enabled and LIVE_MEDIA_CONTENT_ANALYSIS_ENABLED=1. All routes require a valid X-API-Key and bounded X-Service-ID:

Route Behavior
GET /api/content-analysis/probe?streamId=<uuid> Probe object store, FFmpeg, policy, and vendor.
POST /api/content-analysis Execute or replay one exact publication sample.
DELETE /api/content-analysis/:operationId?... Verify release of a succeeded one-shot result.

Apply migration 00013_live_media_content_analysis and configure these values before enabling the provider:

Variable Purpose
LIVE_MEDIA_CONTENT_ANALYSIS_API_KEY Provider credential; never accepted by the API.
LIVE_MEDIA_CONTENT_ANALYSIS_ENDPOINT HTTPS OpenAI-compatible base URL.
LIVE_MEDIA_CONTENT_ANALYSIS_MODEL Bounded provider model identity.
LIVE_MEDIA_CONTENT_ANALYSIS_POLICY_PROFILE Aphrodite-owned advisory policy reference.
LIVE_MEDIA_CONTENT_ANALYSIS_WORKER_ID Stable lease-owner identity.

Loopback HTTP is accepted only to exercise a local provider in tests. Optional bounded controls are LIVE_MEDIA_CONTENT_ANALYSIS_VENDOR_TIMEOUT_MS, LIVE_MEDIA_CONTENT_ANALYSIS_VENDOR_RETRIES, LIVE_MEDIA_CONTENT_ANALYSIS_LEASE_MS, LIVE_MEDIA_CONTENT_ANALYSIS_RENEWAL_MS, LIVE_MEDIA_CONTENT_ANALYSIS_MAXIMUM_ATTEMPTS, LIVE_MEDIA_CONTENT_ANALYSIS_MAXIMUM_SOURCE_BYTES, LIVE_MEDIA_CONTENT_ANALYSIS_MAXIMUM_FRAME_BYTES, and LIVE_MEDIA_CONTENT_ANALYSIS_SAMPLER_TIMEOUT_MS. Renewal must occur before lease expiry. Requests name only an exact ready publication object and stable idempotency identity; callers cannot upload frames, select another tenant or adapter, supply provider keys, or request automatic moderation action.

Durable live recording#

The recording API is available only when the durable pipeline runtime is enabled and LIVE_MEDIA_RECORDING_ENABLED=1. The create and status controls require the deployment INTERNAL_API_KEY plus a bounded X-Service-ID:

Route Behavior
GET /api/recording/probe?streamId=<uuid> Probe publisher, object store, FFmpeg, and policy.
POST /api/recording Queue or replay one bounded recording operation.
GET /api/recording/operations/:id?streamId=<uuid> Read restart-safe queued/processing/terminal state.

Apply migration 00014_live_media_recording before enabling the provider. The base pipeline S3/MinIO configuration is reused for private create-only recording objects; these additional values are required:

Variable Purpose
LIVE_MEDIA_RECORDING_ROOT Absolute private FFmpeg attempt workspace.
LIVE_MEDIA_RECORDING_WORKER_ID Stable durable lease-owner identity.
LIVE_MEDIA_RECORDING_RETENTION_POLICY Aphrodite-owned policy reference accepted by the queue.
MEDIAMTX_RTSP_BASE_URL Operator-owned RTSP(S) base used to derive the stream path.

MEDIAMTX_CONTROL_URL and MEDIAMTX_EDGE_ID must identify the same reconciled edge. Callers provide no media URL, tenant, adapter, worker, object key, or credential. They must name the exact current publisher connection, a unique recording UUID, format (mp4 or matroska), duration, retention reference, operation UUID, and semantic idempotency key. Creation returns 202; the supervised worker performs real capture asynchronously. Interactive stop, DVR, segment tracking, export jobs, and cleanup jobs remain explicit 501 gaps.

Optional bounds are LIVE_MEDIA_RECORDING_POLICY_MAXIMUM_DURATION_SECONDS, LIVE_MEDIA_RECORDING_MAXIMUM_OBSERVATION_AGE_MS, LIVE_MEDIA_RECORDING_LEASE_MS, LIVE_MEDIA_RECORDING_RENEWAL_MS, LIVE_MEDIA_RECORDING_MAXIMUM_ATTEMPTS, LIVE_MEDIA_RECORDING_INITIAL_RETRY_MS, LIVE_MEDIA_RECORDING_MAXIMUM_RETRY_MS, LIVE_MEDIA_RECORDING_SHUTDOWN_GRACE_MS, LIVE_MEDIA_RECORDING_COMPLETION_GRACE_MS, and LIVE_MEDIA_RECORDING_IDLE_INTERVAL_MS. Renewal must occur before lease expiry. Process shutdown aborts the active FFmpeg capture, records retryable durable state while its lease is current, and waits for the worker tick to drain.

Durable HLS segment encryption#

The segment-encryption API is available only when the durable pipeline runtime is enabled and LIVE_MEDIA_SEGMENT_ENCRYPTION_ENABLED=1. Every route requires the deployment INTERNAL_API_KEY plus a bounded X-Service-ID:

Route Behavior
GET /api/segment-encryption/probe?streamId=<uuid> Probe publication, object store, and HSM custody.
POST /api/segment-encryption Queue or replay one exact AES-128 HLS transformation.
GET /api/segment-encryption/operations/:id?streamId=<uuid> Read restart-safe queued/processing/terminal state.
GET /api/segment-encryption/operations/:id/key?streamId=<uuid> Recover exactly 16 bytes for a succeeded operation.

Apply migration 00015_live_media_segment_encryption before enabling the provider. The base pipeline S3/MinIO publication configuration is reused for create-only protected objects; these values are required:

Variable Purpose
LIVE_MEDIA_SEGMENT_ENCRYPTION_WORKER_ID Stable durable lease-owner identity.
LIVE_MEDIA_SEGMENT_ENCRYPTION_KEY_REFERENCE Aphrodite-owned public AES-128 policy reference.
LIVE_MEDIA_SEGMENT_ENCRYPTION_KEY_VERSION Positive fixed policy version.
LIVE_MEDIA_SEGMENT_ENCRYPTION_KEY_BASE_URI HTTPS internal key-delivery base; loopback HTTP tests.
LIVE_MEDIA_SEGMENT_ENCRYPTION_PKCS11_MODULE Absolute PKCS#11 provider module path.
LIVE_MEDIA_SEGMENT_ENCRYPTION_PKCS11_TOKEN_LABEL Operator-provisioned HSM/token label.
LIVE_MEDIA_SEGMENT_ENCRYPTION_PKCS11_PIN HSM PIN read only by the PKCS#11 backend process.
LIVE_MEDIA_SEGMENT_ENCRYPTION_HSM_KEK_ID Existing nonextractable RSA-3072 KEK object ID.

LIVE_MEDIA_SEGMENT_ENCRYPTION_PKCS11_EXECUTABLE may select a non-default pkcs11-tool. The configured key base URI must end at the mounted operations collection (normally /api/segment-encryption/operations); the provider appends the operation/key path and exact stream query. Lease/retry and graph bounds are configurable with LIVE_MEDIA_SEGMENT_ENCRYPTION_LEASE_MS, LIVE_MEDIA_SEGMENT_ENCRYPTION_RENEWAL_MS, LIVE_MEDIA_SEGMENT_ENCRYPTION_MAXIMUM_ATTEMPTS, LIVE_MEDIA_SEGMENT_ENCRYPTION_INITIAL_RETRY_MS, LIVE_MEDIA_SEGMENT_ENCRYPTION_MAXIMUM_RETRY_MS, LIVE_MEDIA_SEGMENT_ENCRYPTION_MAXIMUM_OBJECTS, LIVE_MEDIA_SEGMENT_ENCRYPTION_MAXIMUM_MANIFEST_BYTES, LIVE_MEDIA_SEGMENT_ENCRYPTION_MAXIMUM_SEGMENT_BYTES, and LIVE_MEDIA_SEGMENT_ENCRYPTION_MAXIMUM_TOTAL_BYTES. Renewal must precede lease expiry. Partial HSM configuration, a mismatched key policy, unsafe remote HTTP, and invalid bounds prevent startup.

The provider currently supports only HLS AES-128-CBC over complete MPEG-TS VOD graphs. CENC/CBCS, vendor DRM/CDM licensing, viewer/client integration, and protected-object/key cleanup are not exposed as working capabilities. Key delivery is an internal authenticated media operation with strict no-store headers, not an external DRM license endpoint.

Durable visible watermarking#

The watermark API is available only when the durable pipeline runtime is enabled and LIVE_MEDIA_WATERMARK_ENABLED=1. Every route requires the deployment INTERNAL_API_KEY plus a bounded X-Service-ID:

Route Behavior
GET /api/watermark/probe?streamId=<uuid> Probe publication/object, FFmpeg, and HSM dependencies.
POST /api/watermark Queue or replay one exact visible-grid transform.
GET /api/watermark/operations/:id?streamId=<uuid> Read restart-safe queued/processing/terminal state.
DELETE /api/watermark/operations/:id?streamId=<uuid> Delete output/evidence and durably fence recreation.

Apply migration 00016_live_media_watermark before enabling the provider. The base pipeline S3/MinIO publication configuration is reused for source reads and create-only output. These values are required:

Variable Purpose
LIVE_MEDIA_WATERMARK_WORKER_ID Stable durable lease-owner identity.
LIVE_MEDIA_WATERMARK_KEY_REFERENCE Aphrodite-owned public watermark key policy.
LIVE_MEDIA_WATERMARK_KEY_VERSION Positive fixed policy version.
LIVE_MEDIA_WATERMARK_PKCS11_MODULE Absolute PKCS#11 provider module path.
LIVE_MEDIA_WATERMARK_PKCS11_TOKEN_LABEL Operator-provisioned HSM/token label.
LIVE_MEDIA_WATERMARK_PKCS11_PIN HSM PIN read only by the PKCS#11 backend process.
LIVE_MEDIA_WATERMARK_HSM_KEK_ID Existing nonextractable RSA-3072 KEK object ID.

LIVE_MEDIA_WATERMARK_PKCS11_EXECUTABLE may select a non-default pkcs11-tool. The existing LIVE_MEDIA_FFMPEG_BINARY and LIVE_MEDIA_FFPROBE_BINARY overrides are honored. Lease/retry, byte, quality, and execution bounds are configurable with LIVE_MEDIA_WATERMARK_LEASE_MS, LIVE_MEDIA_WATERMARK_RENEWAL_MS, LIVE_MEDIA_WATERMARK_MAXIMUM_ATTEMPTS, LIVE_MEDIA_WATERMARK_INITIAL_RETRY_MS, LIVE_MEDIA_WATERMARK_MAXIMUM_RETRY_MS, LIVE_MEDIA_WATERMARK_MAXIMUM_SOURCE_BYTES, LIVE_MEDIA_WATERMARK_MAXIMUM_OUTPUT_BYTES, LIVE_MEDIA_WATERMARK_MINIMUM_PSNR_DB, LIVE_MEDIA_WATERMARK_FFMPEG_TIMEOUT_MS, and LIVE_MEDIA_WATERMARK_IDLE_INTERVAL_MS. Renewal must precede lease expiry. Partial HSM configuration and invalid bounds prevent startup.

Callers name an operation/idempotency identity, exact ready publication, published MPEG-TS source key and digest, and optionally a viewer session. They cannot select the tenant, adapter, visible-grid profile, watermark payload, key, output path, or worker. A non-null viewer session must be active and entitlement-valid for the exact tenant and stream. The result is a visible keyed 8x8 grid with measured pixel extraction and PSNR evidence; it is not represented as an invisible or forensically robust watermark.

Protected origin authorization#

GET /media-origin/authorize/<exact-object-key> is an authorization-subrequest endpoint for the external HLS/DASH origin proxy. Forward the viewer's Bearer grant and the exact requested object path. A valid current grant returns 204 plus tenant/stream/publication routing headers; missing, malformed, expired, wrong-object, or revoked grants all return an indistinguishable empty 401. The endpoint does not impersonate S3/CDN byte serving. The proxy must enforce the returned decision and fetch from the private bucket.

Viewer issuance and origin verification must share:

  • LIVE_MEDIA_PLAYBACK_ENABLED=1
  • LIVE_MEDIA_PLAYBACK_KEY_ID
  • LIVE_MEDIA_PLAYBACK_HMAC_SECRET (at least 32 bytes)
  • LIVE_MEDIA_ORIGIN_BASE_URL (HTTPS, except loopback HTTP in tests)

Optional bounded settings are LIVE_MEDIA_PLAYBACK_LIFETIME_SECONDS and LIVE_MEDIA_PLAYBACK_CLOCK_SKEW_SECONDS. Every authorization re-reads both the forced-RLS publication ledger and the active viewer lease, so publication revocation, lease expiry, reconnect fencing, and leave are immediate across process restarts.

Working on this package#

The fastest local loop is via Nx:

bash
pnpm nx test aphrodite-streaming
pnpm nx lint aphrodite-streaming
pnpm nx build aphrodite-streaming

When Nx is unhappy (usually because another worktree has duplicate project names), bypass it with the underlying tools from this directory:

bash
npx tsc --noEmit
npx vitest run

See the root README for monorepo-wide conventions (catalog deps, commit format, git workflow). See the Contributor Guide for the full PR workflow.