@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:
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=1LIVE_MEDIA_PLAYBACK_KEY_IDLIVE_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:
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:
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.