Service: Continue Watching Service - EyevinnOSC/community GitHub Wiki

Continue Watching Service

The Continue Watching Service (serviceId eyevinn-continue-watching-api, catalog page) is an open source REST API that stores and returns playback positions per user and asset, so an OTT or VOD application can offer "resume where you left off" across devices. It is a long-running service instance. License: MIT.

What it can do

  • Store the last playback position (in seconds) for a user and an asset.
  • Return the stored position for a given user and asset.
  • List all stored positions for a user, newest first.
  • Persist data in a Redis-compatible database such as OSC Valkey.

Creating an instance

The service needs a Redis-compatible database. Create a Valkey instance first (serviceId valkey-io-valkey, see Valkey) and confirm it is running.

  1. create-service-instance with serviceId: "valkey-io-valkey" and config { "name": "continuestore" }.
  2. describe-service-instance for the Valkey instance to read its host and port (the internal endpoint can be used from other OSC services in the same workspace).
  3. Create the Continue Watching Service with serviceId: "eyevinn-continue-watching-api":
{
  "name": "mywatchtracker",
  "RedisHost": "<valkey-host>",
  "RedisPort": "<valkey-port>"
}
  1. Verify with wait-for-service-ready or get-instance-status, then describe-service-instance for the URL.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
RedisHost Yes string Host of the Redis-compatible database. Corresponds to the REDIS_URL variable of the upstream service, which is used as the Redis host (not a full URL).
RedisPort No string Port of the Redis server. Upstream default is 6379.
RedisUsername No string Redis username, if the database uses one. Leave empty otherwise.
RedisPassword No string, sensitive Redis password. Required if your Valkey instance has a password; store as a service secret and pass {{secrets.NAME}}.

{{secrets.NAME}} must be the entire field value. Overwriting a secret does not restart a running instance.

Using the instance

The API (from the upstream source) uses these endpoints, with position in seconds:

# Store a position
curl -X POST https://<instance-url>/position/<userId>/<assetId>/<position>

# Get the position for one asset (404 if none stored)
curl https://<instance-url>/position/<userId>/<assetId>

# List all positions for a user, newest first
curl https://<instance-url>/position/<userId>

Note: OSC gates instance URLs (everything except /) with authentication unless the service defines public paths, so calls from your application must carry valid credentials.

Example with the OSC CLI:

npx @osaas/cli create eyevinn-continue-watching-api mywatchtracker \
  -o RedisHost="<valkey-host>" -o RedisPort="<valkey-port>"

Resources

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