TAMS Gateway is an open source REST API gateway that implements the Time-addressable Media Store (TAMS) specification. TAMS defines a standard way to store and retrieve segmented media flows using time-based addressing: each media segment is indexed by its start time, which makes it easy to seek, splice, and replay content without scanning entire files. Available as an open web service in Eyevinn Open Source Cloud, TAMS Gateway combines a CouchDB metadata index with S3-compatible object storage to give your applications a standards-compliant media store. It also ships with a built-in HLS playback endpoint and a read-only inspector UI. This tutorial walks you through getting started.

Want the whole stack in one click? There is now a TAMS Gateway Solution that provisions the gateway together with its CouchDB and MinIO backing services as a single deployment. Use this Service guide when you want to run the gateway against your own (or an existing) CouchDB and S3 storage.

• If you have not already done so, sign up for an Eyevinn OSC account
• A paid OSC plan (required for database services)

TAMS Gateway uses CouchDB to store the media flow index. Navigate to the CouchDB service in the Eyevinn OSC web console. Click Create couchdb and enter a name and an admin password for the instance.

Once running, click the instance card and note the instance URL. The gateway automatically creates the required CouchDB databases and the segment index on startup, so you do not need to create any databases by hand.

TAMS Gateway stores media segments in S3-compatible object storage. You can use AWS S3 or an OSC-managed MinIO instance.

To use MinIO on OSC:

1. Navigate to the MinIO service and click Create objstorage. Give it a name, a RootUser, and a RootPassword.
2. From the instance details, note the endpoint URL, the RootUser (access key ID), and the RootPassword (secret access key).
3. Create a bucket. The gateway never creates buckets, so the bucket must already exist before the gateway starts. Open the MinIO instance URL in your browser, log in with the RootUser and RootPassword, and create a bucket (for example tams). Note the bucket name.

Navigate to the TAMS Gateway service. Go to the Service Secrets tab and store your sensitive values so you can reference them as {{secrets.<name>}} instead of pasting them in plain text:

• dbpassword: your CouchDB admin password
• awssecret: your S3 secret access key (the MinIO RootPassword)

Go to My tams-gateways and click Create tams-gateway. Fill in:

• name: a name for your instance (alphanumeric and underscores only)
• DbUrl: the CouchDB connection URL (for example http://admin:{{secrets.dbpassword}}@<IP>:<PORT>)
• DbUsername: admin
• DbPassword: {{secrets.dbpassword}}
• AwsAccessKeyId: your S3 access key ID (the MinIO RootUser)
• AwsSecretAccessKey: {{secrets.awssecret}}
• S3Bucket (required): the bucket you created in Step 2 (for example tams)
• S3EndpointUrl (optional): endpoint URL for non-AWS S3 storage (for example your MinIO URL). Leave it unset for native AWS S3 and the SDK resolves the endpoint from AwsRegion.

Optional fields: AwsRegion (default eu-north-1), CorsOrigin (comma-separated allowlist, needed for browser playback), LogLevel.

Note on authentication. There is no token field to set here. On OSC the gateway runs behind the OSC ingress access gate, which authenticates every request with a Service Access Token (SAT) before it reaches the gateway. See Step 5.

Click the instance card when the status is green and running. The TAMS API is served at the instance URL.

A catalog service instance sits behind the OSC access gate. Every path except the root liveness check (/) requires a valid SAT, so you authenticate with the gate rather than with a gateway-specific token.

Go to Settings (bottom left of the OSC console) and open the API tab. Copy your Personal Access Token (PAT). Then, with npm installed, mint a SAT for the gateway service:

export OSC_ACCESS_TOKEN=<YOUR_PAT>
npx -y @osaas/cli service-access-token eyevinn-tams-gateway

Send the SAT on every request, either as a bearer token:

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 refresh it (re-mint, or refresh lazily 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.m3u8 synthesises 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=vod for a complete playlist or ?type=live for the live edge, and ?timerange=[start_end) to restrict the window. Only MPEG-TS (H.264/AAC) flows are playable; others return 415. Browser playback also needs a CORS policy on the object store allowing GET and Range from 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 /ui for 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>"

• TAMS Gateway on GitHub
• TAMS Gateway Solution (one-click full stack)
• BBC TAMS Specification
• TAMS API Reference