Service: Open Videocore - EyevinnOSC/community GitHub Wiki

Open Videocore

Open Videocore (serviceId eyevinn-open-videocore) is a headless media asset management (MAM) system from Eyevinn Technology. It stores, transcodes, packages and delivers video content through a single API. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. License: Apache-2.0. It integrates SVT Encore for transcoding, Shaka Packager for packaging, MinIO for object storage and CouchDB for the asset catalogue, and provisions those as separate OSC service instances in your workspace.

What it can do

  • Ingest sources from a URL, a direct upload, a presigned upload, multipart upload of large files, or a watch folder in a bucket.
  • Transcode with SVT Encore profiles (auto-scaled Encore instances), and package for adaptive streaming (HLS/DASH).
  • Return playback manifest URLs or a presigned download URL for the source.
  • Thumbnails and poster frames, clip and trim into a new asset, container re-wrap without re-encode, technical metadata extraction, audio and subtitle track management, collections, full-text and metadata search, and bucket management.
  • Webhooks for asset and job lifecycle events, and a built-in ops dashboard at /ui and interactive API docs at /api-docs.

Creating an instance

Prerequisites: an OSC account on a paid plan, an OSC Personal Access Token (PAT), and a Parameter Store (see Service: App Config Service, serviceId eyevinn-app-config-svc). Getting from a new instance to a playable asset takes five steps: create the instance, provision a media stack, bootstrap the transcoding profiles, ingest a source, and transcode it. Provisioning and bootstrapping are required before the first ingest.

  1. Create the Parameter Store instance and note its name and its API key, which is shown once when it is created and cannot be read back.
  2. Store sensitive values as service secrets with create-service-secret (serviceId eyevinn-open-videocore): for example miniopwd (MinIO root password), couchdbpwd (CouchDB admin password), oscpat (your PAT) and paramstorekey (the Parameter Store API key). Pick strong passwords and keep your own copy; they are not shown again.
  3. Create the instance with create-service-instance, serviceId: "eyevinn-open-videocore":
{
  "name": "myvideocore",
  "OscAccessToken": "{{secrets.oscpat}}",
  "ParameterStoreApiKey": "{{secrets.paramstorekey}}",
  "ParameterStore": "my-param-store",
  "MinioRootPassword": "{{secrets.miniopwd}}",
  "CouchdbAdminPassword": "{{secrets.couchdbpwd}}"
}

With the OSC CLI:

osc create eyevinn-open-videocore myvideocore \
  -o OscAccessToken="{{secrets.oscpat}}" \
  -o ParameterStoreApiKey="{{secrets.paramstorekey}}" \
  -o ParameterStore="my-param-store" \
  -o MinioRootPassword="{{secrets.miniopwd}}" \
  -o CouchdbAdminPassword="{{secrets.couchdbpwd}}"

Use wait-for-service-ready or get-instance-status, then describe-service-instance for the instance URL, written as https://<instance-url> below. Then follow "Using the instance" to provision a stack and bootstrap profiles.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
OscAccessToken Yes string, sensitive OSC Personal Access Token Open Videocore uses to create storage, a database, a queue and Encore transcoders (and the packager) in your workspace on your behalf. The catalog notes it is filled in automatically when created from the console; when creating through MCP supply your own PAT as a secret, as in the example.
ParameterStoreApiKey Yes string, sensitive API key of the Parameter Store, shown once when the store was created. It cannot be read back, so use your saved copy.
ParameterStore Yes string Name of an existing Parameter Store, for example ovcconfig. Create the store first. Open Videocore uses it to remember which services belong to which media stack.
MinioRootPassword Yes string, sensitive Root password of the MinIO object storage that holds source files and packaged output.
CouchdbAdminPassword Yes string, sensitive Admin password of the CouchDB database holding asset metadata (technical details, tags, collections).
EncoreMaxInstances No string Maximum number of concurrent transcoding jobs; each transcoder handles one job. Extra jobs queue and start as slots free up. It scales up only under a real backlog, and each running transcoder costs tokens, so this is also your cost ceiling. Default 2. Keep at 1 while testing.
EncoreMinInstances No string Number of transcoder instances kept running even when idle. Default 0, which lets the stack scale to zero so you pay nothing for transcoding while idle. 1 or more removes the wait before the first job but you pay the full daily rate per instance continuously.
EncoreIdleTimeoutMs No string How long an idle transcoder waits before shutting itself down, in milliseconds. Shorter saves tokens but a job arriving soon after the last pays the startup delay again; longer keeps a warm instance at the cost of idle time. For bursty workloads set it longer than the typical gap within a burst.
ENCORE_PROFILES_URL No string URL of a custom Encore profiles index. When set, Encore instances use this instead of the auto-derived PUBLIC_BASE_URL path.
ENCORE_PROFILES_URL_OVERRIDE No string Forces all Encore instances to use this profiles URL, overriding the derived PUBLIC_BASE_URL path and any parameter-store value.
TrustRoleHeader No string Default off; only the exact string true enables it. Enable only behind a fronting layer (reverse proxy or identity provider) that strips any client-supplied X-OVC-Role header and injects the authenticated caller's real role. Otherwise the header is attacker-controlled and every caller resolves to admin. When off, the header is stripped and every caller resolves to admin.

Secret options: OscAccessToken, ParameterStoreApiKey, MinioRootPassword, CouchdbAdminPassword. Pass them as {{secrets.NAME}}, as the entire field value. The three Encore* options can be read from GET /api/v1/scaler/status and changed at runtime without a restart via PATCH /api/v1/scaler/config (see "Tuning the Encore auto-scaler"). Other options are not updatable in place: Open Videocore does not support configuration changes with update-service-instance; delete the instance and create a new one.

Token costs

Open Videocore is an orchestration layer. Its own service rate covers only the Open Videocore instance; everything it provisions is a separate OSC service instance in your workspace with its own token rate, billed to you. The on-demand Encore instances are by far the largest component.

Always running once a stack is provisioned:

Service What it does
eyevinn-open-videocore the API and orchestrator itself
minio-minio object storage for sources and packaged output
apache-couchdb the asset catalogue
valkey-io-valkey the job queue

Provisioned on demand and torn down again:

Service When it appears
encore spun up by the auto-scaler when transcode jobs arrive, torn down after EncoreIdleTimeoutMs of idle time. The dominant cost.
eyevinn-encore-packager created lazily on the first packaging job, then reused; removed when the stack is deprovisioned
eyevinn-ffmpeg-s3 per-job, for technical metadata extraction

Rates are quoted per instance-day and are ceilings, so a stack whose Encore instances scale to zero between jobs bills well below the ceiling. See Pricing. If jobs arrive in bursts, lower EncoreIdleTimeoutMs; if they arrive steadily, a higher timeout avoids the cold start on every job.

Using the instance

Provision a media stack

Required before you can ingest anything. It stands up MinIO, CouchDB and Valkey for the workspace. Encore is created later by the auto-scaler when the first transcode job arrives, and the packager on the first packaging job.

curl -s -X POST https://<instance-url>/api/v1/provision/ \
  -H "Content-Type: application/json" \
  -d '{"name": "mystack"}'

Provisioning is asynchronous. The call returns an operationId; poll until status is done:

curl -s https://<instance-url>/api/v1/provision/operations/<operationId>

List, inspect or tear down stacks:

curl -s https://<instance-url>/api/v1/provision/
curl -s https://<instance-url>/api/v1/provision/mystack
curl -s -X DELETE https://<instance-url>/api/v1/provision/mystack

By default the stack provisions its own MinIO instance and buckets. To use an existing AWS-region or S3-compatible bucket instead, pass the optional sourceStorage and packagedStorage blocks; see the provisioning with external S3-compatible storage guide.

Bootstrap the transcoding profiles

Also required: it seeds the profile store from the default Encore profile index. Without it there are no profiles for a transcode job.

curl -s -X POST https://<instance-url>/api/v1/profiles/bootstrap

Pass ?force=true to re-seed. Profiles are stored in CouchDB and managed through /api/v1/profiles or the Profiles tab of the ops dashboard.

Ingest a source video

curl -s -X POST https://<instance-url>/api/v1/assets/ingest-url \
  -H "Content-Type: application/json" \
  -d '{"sourceUrl": "https://example.com/source.mp4", "name": "My first asset"}'

Only sourceUrl is required; name, description, title and tags are optional. The response contains { assetId, jobId }; use assetId (not id) in later calls. Other routes: PUT /api/v1/assets/:id/upload (direct upload), POST /api/v1/assets/:id/upload-url (presigned single-part upload), the POST /api/v1/assets/:id/multipart/initiate family (large files), and watch-folder ingest through /api/v1/storage/buckets/:bucket/watch-folder/toggle.

Transcode

curl -s -X POST https://<instance-url>/api/v1/assets/<asset-id>/transcode \
  -H "Content-Type: application/json" \
  -d '{"profile": "program"}'

All body fields are optional: profile names a bootstrapped profile, customProfile supplies profile YAML inline, profileParams passes parameters to a parametrised profile. This call causes the first Encore instance to be created, so the first job on a cold pool takes longer. Track progress with GET /api/v1/jobs/ and GET /api/v1/jobs/<job-id>.

Package for adaptive streaming

Transcode and package together:

curl -s -X POST https://<instance-url>/api/v1/assets/<asset-id>/execute \
  -H "Content-Type: application/json" \
  -d '{"pipeline": "abr-vod"}'
curl -s https://<instance-url>/api/v1/pipelines/<executionId>

Packaging only, after transcoding: POST /api/v1/assets/<asset-id>/package.

The first packaging call can time out with 504: the packager is provisioned lazily and on a cold workspace that can take 60 to 90 seconds, longer than the 60-second ingress timeout. The pipeline was still created and runs in the background; poll GET /api/v1/pipelines/<executionId> (for execute) or GET /api/v1/jobs/<job-id> (for package). Later packaging calls are fast.

Get playback URLs

curl -s https://<instance-url>/api/v1/assets/<asset-id>/delivery

Returns the packaged HLS/DASH manifest URLs, or a presigned download URL for the source.

Webhooks

Register a webhook instead of polling /api/v1/jobs/:

curl -s -X POST https://<instance-url>/api/v1/webhooks/ \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/videocore",
    "events": ["transcode.complete", "transcode.failed"],
    "secret": "<shared-secret-for-signature-verification>"
  }'

url and events are required, secret is optional. Events: asset.ready, asset.failed, transcode.complete, transcode.failed, package.complete, package.failed. List with GET /api/v1/webhooks/, remove with DELETE /api/v1/webhooks/<id>.

Other capabilities

Capability Endpoint
Thumbnails / poster frames POST and GET /api/v1/assets/:id/thumbnails
Clip and trim into a new asset POST /api/v1/assets/:id/clip
Container re-wrap without re-encode POST /api/v1/assets/:id/export
Technical metadata extraction POST /api/v1/assets/:id/extract-metadata
Audio and subtitle track management /api/v1/assets/:id/tracks, /audio-tracks, /subtitle-tracks
Collections /api/v1/collections
Full-text and metadata search GET /api/v1/search/
Object storage and buckets /api/v1/storage/buckets

GET /api/v1/assets/search is a deprecated free-text-only alias; use GET /api/v1/search/.

Tuning the Encore auto-scaler

curl -s https://<instance-url>/api/v1/scaler/status
curl -s https://<instance-url>/api/v1/scaler/config
curl -s -X PATCH https://<instance-url>/api/v1/scaler/config \
  -H "Content-Type: application/json" \
  -d '{"maxInstances": 3, "idleTimeoutMs": 120000}'

maxInstances, minInstances and idleTimeoutMs change at runtime without a restart; idleTimeoutMs must be at least 10000. scalerActive reads false until a stack is provisioned and activates immediately after provisioning completes.

Common status codes

Code Meaning What to do
501 Stack not yet provisioned Run POST /api/v1/provision/ and wait until status is done
502 Packager provisioning failed Check that the PAT in the config has permission to create service instances
409 pipeline_running Another pipeline is already running for this asset Wait for it to complete, then retry
504 First packaging call timed out while the packager was provisioned The pipeline was still created; poll the pipeline or job

Limitations

  • Configuration is not updatable in place with update-service-instance; delete and recreate (auto-scaler settings are the exception).
  • Asset data lives in MinIO and CouchDB within the stack. Deleting the instance deletes all stored assets and the asset catalogue.
  • Provisioning and profile bootstrap are one-time per stack but both are required before the first ingest. A 404 or empty profile list on the first transcode almost always means one was skipped.

Resources

⚠️ **GitHub.com Fallback** ⚠️