Service: Open Videocore - EyevinnOSC/community GitHub Wiki
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.
- 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
/uiand interactive API docs at/api-docs.
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.
- 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.
- Store sensitive values as service secrets with
create-service-secret(serviceIdeyevinn-open-videocore): for exampleminiopwd(MinIO root password),couchdbpwd(CouchDB admin password),oscpat(your PAT) andparamstorekey(the Parameter Store API key). Pick strong passwords and keep your own copy; they are not shown again. - 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.
| 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.
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.
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/mystackBy 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.
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/bootstrapPass ?force=true to re-seed. Profiles are stored in CouchDB and managed through /api/v1/profiles or the Profiles tab of the ops dashboard.
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.
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>.
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.
curl -s https://<instance-url>/api/v1/assets/<asset-id>/deliveryReturns the packaged HLS/DASH manifest URLs, or a presigned download URL for the source.
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>.
| 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/.
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.
| 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 |
- 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
404or empty profile list on the first transcode almost always means one was skipped.
- GitHub repository
- Service: SVT Encore, the transcoding engine used internally
- Service: App Config Service, the Parameter Store
- Pricing