Service: TAMS Gateway - EyevinnOSC/community GitHub Wiki
TAMS Gateway (serviceId eyevinn-tams-gateway, license MIT) is an open source REST API gateway that implements the Time-addressable Media Store (TAMS) specification: segmented media flows are stored and retrieved with time-based addressing, each segment indexed by its start time. It combines a CouchDB metadata index with S3-compatible object storage. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance.
A TAMS Gateway Solution provisions the gateway together with its CouchDB and MinIO backing services as a single deployment. Use this page when you run the gateway against your own or an existing CouchDB and S3 storage.
- Store and index segmented media flows through the standard TAMS REST API (flows, sources, segments, storage, deletion requests, per-property and per-tag editing, webhooks, service descriptors).
- Synthesise an HLS media playlist on the fly from MPEG-TS flows (
/flows/{id}/output.m3u8). - Serve a built-in read-only inspector UI at
/uiand Swagger UI at/docs. - Store segment objects in AWS S3 or S3-compatible storage such as MinIO.
Create dependencies first and confirm they are running. A paid OSC plan is required for database services.
- CouchDB (
apache-couchdb) stores the segment index. The gateway automatically creates the required databases and segment index on startup. Create it with a name and anAdminPassword; usedescribe-service-instancefor the URL. - S3-compatible storage, for example MinIO (
minio-minio) withRootUserandRootPassword. Create the bucket yourself first: the gateway never creates buckets, it only allocates object keys within an existing bucket (for example a bucket calledtams).
Store sensitive values with create-service-secret (serviceId eyevinn-tams-gateway), for example dburl (the whole CouchDB URL such as http://admin:<password>@<IP>:<PORT>), dbpassword (CouchDB admin password) and awssecret (S3 secret key, the MinIO RootPassword). Then call create-service-instance with serviceId: "eyevinn-tams-gateway":
{
"name": "mygw",
"DbUrl": "{{secrets.dburl}}",
"DbUsername": "admin",
"DbPassword": "{{secrets.dbpassword}}",
"AwsAccessKeyId": "<minio-root-user>",
"AwsSecretAccessKey": "{{secrets.awssecret}}",
"S3Bucket": "tams",
"S3EndpointUrl": "https://<minio-url>"
}{{secrets.NAME}} works only as the entire field value, so it cannot be embedded inside a URL; put the complete DbUrl in one secret. Leave S3EndpointUrl unset for native AWS S3 and the SDK resolves the endpoint from AwsRegion.
There is no gateway token option. On OSC the gateway runs behind the OSC access gate, which authenticates every request with a Service Access Token (SAT); see "Authentication" below.
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Letters, digits and underscore (^\w+$); OSC limits names to 20 characters. |
| DbUrl | Yes | string, sensitive | Connection URL of the CouchDB database holding the TAMS segment index and metadata, for example http://admin:<password>@<IP>:<PORT>. On OSC this is the link to your CouchDB instance. |
| DbUsername | Yes | string | Username for the CouchDB database. With OSC CouchDB this is typically admin. |
| DbPassword | Yes | string, sensitive | Password for the CouchDB database. With OSC CouchDB this is the AdminPassword set at creation. |
| AwsAccessKeyId | Yes | string, sensitive | Access key ID for the S3-compatible storage where segments are stored. With OSC MinIO this is the RootUser. |
| AwsSecretAccessKey | Yes | string, sensitive | Secret access key for the S3-compatible storage. With OSC MinIO this is the RootPassword. |
| S3Bucket | Yes | string | Name of the existing bucket for media segments (for example tams). The gateway does not create it. |
| S3EndpointUrl | No | string | Endpoint URL for non-AWS S3-compatible storage such as MinIO. Leave unset for native AWS S3. |
| AwsRegion | No | string | AWS region of the S3 bucket. The earlier page states a default of eu-north-1. |
| CorsOrigin | No | string | Comma-separated allowlist of origins for CORS; needed for browser playback. |
| LogLevel | No | string | Logging verbosity. Accepted values not verified. |
Sensitive options (DbUrl, DbPassword, AwsAccessKeyId, AwsSecretAccessKey) should be supplied as {{secrets.NAME}}.
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Instance name. |
| AdminPassword | Yes | string, sensitive | Password for the administrator. OSC can generate it. |
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Instance name. |
| RootUser | No | string | Admin user name; the S3 access key (AWS_ACCESS_KEY_ID) for clients. OSC can generate it. |
| RootPassword | No | string, sensitive | Admin password; the S3 secret key (AWS_SECRET_ACCESS_KEY). Must match ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{10,}$. OSC can generate it. |
A catalog service instance sits behind the OSC access gate. Every path except the root liveness check (/) requires a valid SAT. Create a Personal Access Token (PAT) (see Finding Your API Token), then mint a SAT for the gateway service:
export OSC_ACCESS_TOKEN=<YOUR_PAT>
npx -y @osaas/cli service-access-token eyevinn-tams-gatewaySend the SAT on every request as Authorization: Bearer <SAT>, or on the x-jwt header (x-jwt: Bearer <SAT>), or as a {serviceId}.sat cookie. A request without a valid SAT returns 401 from the gate. The SAT is short-lived (about 1 hour); automated clients should re-mint it, or refresh on a 401.
The gateway exposes the standard TAMS REST API. A typical write-then-read cycle:
GW=https://<instance-url>
AUTH="Authorization: Bearer <SAT>"
# 1. Create (or update) a flow. The gateway also creates the source automatically.
curl -X PUT "$GW/flows/<flow-id>" -H "$AUTH" -H "Content-Type: application/json" -d '{
"id": "<flow-id>",
"source_id": "<source-id>",
"format": "urn:x-nmos:format:video",
"codec": "video/mp2t"
}'
# 2. Allocate storage. The response holds media_objects[].put_url.url and object_id.
curl -X POST "$GW/flows/<flow-id>/storage" -H "$AUTH"
# 3. Upload each segment to its presigned put_url.url with an HTTP PUT, then
# register the segment (timerange is TAMS "[<sec>:<ns>_<sec>:<ns>)", TAI).
curl -X POST "$GW/flows/<flow-id>/segments" -H "$AUTH" -H "Content-Type: application/json" -d '{
"object_id": "<object_id from step 2>",
"timerange": "[0:0_2:0)"
}'
# 4. Read back segments for a timerange (returns presigned GET URLs).
curl "$GW/flows/<flow-id>/segments?timerange=[0:0_2:0)" -H "$AUTH"Interactive API documentation (Swagger UI) is served at <instance-url>/docs. On a gated catalog instance the gate also protects /docs, so open it with a client that sends the SAT header.
The gateway adds two capabilities on top of the raw TAMS API:
-
HLS output.
GET /flows/{id}/output.m3u8synthesises an HLS media playlist on the fly from a flow's MPEG-TS segments, so any TS flow is directly playable in a standard HLS client (hls.js, Safari, Omakase Player). Use?type=vodfor a complete playlist or?type=livefor the live edge, and?timerange=[start_end)to restrict the window. Only MPEG-TS (H.264/AAC) flows are playable; others return415. Browser playback also needs a CORS policy on the object store allowingGETandRangefrom the player origin. -
Inspector UI. A built-in, read-only inspector is served at
/ui(enabled by default). It browses sources, flows, and segments and plays a flow with an embedded HLS player. The inspector inherits the deployment's auth and is not public. On a gated catalog instance the gate blocks/uifor a plain browser (every path needs the SAT), so the inspector is most directly reachable when the gateway runs standalone, locally, or behind a browser-friendly front. See the TAMS Gateway repository for details.
The full endpoint list (flows, sources, segments, storage, deletion requests, per-property and per-tag editing, webhooks, and service descriptors) is documented in the gateway readme and at /docs.
osc create eyevinn-tams-gateway mygw \
-o DbUrl="http://admin:mypassword@<IP>:<PORT>" \
-o DbUsername="admin" \
-o DbPassword="mypassword" \
-o AwsAccessKeyId="myaccesskey" \
-o AwsSecretAccessKey="mysecretkey" \
-o S3Bucket="tams" \
-o S3EndpointUrl="https://<minio-url>"