Skip to content
SyncTV SyncTV Docs

Common Workflows

Choose the Goal

Section titled “Choose the Goal”

Start from the goal you are handling. These workflows keep the operating order; field, API, and configuration details live in the linked topic pages.

User Workflows

Section titled “User Workflows”
  1. Sign in and confirm email, 2FA, or OAuth2 status.
  2. Create a room or open an existing room entry point.
  3. Submit a password or join review if the room requires it.
  4. Add media or choose an existing playlist item.
  5. Start playback if you have permission, otherwise wait for a room administrator.
  6. If playback fails, refresh the playback info and check whether proxy playback is required.

Room Administrator Workflows

Section titled “Room Administrator Workflows”

Create a Controlled Room

Section titled “Create a Controlled Room”
  1. Create a room with a clear name and description.
  2. Set a room password if needed.
  3. Enable requireApproval for semi-public rooms.
  4. Set maxMembers according to service and upstream Provider capacity.
  5. Review member and guest default permissions.
  6. Join once with a normal account to validate the path.

Handle Member Issues

Section titled “Handle Member Issues”
GoalActionNote
Temporary muteRemove send_chat from the memberLower impact than disabling chat room-wide
Grant playback controlAdd play_controlAdd change_current_media for media switching
Remove disruptive memberKick the member or platform-ban the userRoom ban is not a platform ban
Long-term responsibilityAdjust role or defaultsAvoid large stacks of personal overrides

See Permissions Model and Rooms, Permissions, and Preferences for details.

Platform Administrator Workflows

Section titled “Platform Administrator Workflows”

Launch Validation

Section titled “Launch Validation”
  1. Follow the Production Checklist for secrets, database, Redis, TLS, and backups.
  2. Run synctv config validate --strict.
  3. Check /health/ready.
  4. Sign in as root, create a normal user, and create a test room.
  5. Validate WebSocket, chat, playback control, Provider browse, and proxy playback.
  6. Enable metrics and confirm scraping.
  7. Perform a PostgreSQL and secret restore drill.

Add a Media Provider

Section titled “Add a Media Provider”
  1. Decide between a local Provider and a remote Provider instance.
  2. Configure or create the Provider instance and ensure credential encryption is configured.
  3. Test login, browse, search, and playback with an administrator.
  4. Test both direct and proxy playback.
  5. For Range-capable upstreams, verify seek and slice cache behavior.
  6. Give users a clear default Provider or usage guidance.

See Add Media.

Developer Workflows

Section titled “Developer Workflows”

Bring Up a Client

Section titled “Bring Up a Client”
  1. Read Client Integration Guide for HTTP, gRPC, and WebSocket boundaries.
  2. Start the service with OpenAPI and export /api-docs/openapi.json.
  3. Generate an SDK or write minimal requests.
  4. Implement login and refresh token handling.
  5. Create a WebSocket ticket and connect to /ws/rooms/{roomId}.
  6. Use Realtime API to observe playback state, playback info, room settings, and members.
  7. Handle status, code, requestId, and Retry-After using Errors.

Add or Change an API

Section titled “Add or Change an API”
  1. Choose HTTP/OpenAPI, gRPC, or Realtime.
  2. Update proto or handler while keeping errors and permissions consistent.
  3. Add tests and update OpenAPI or protobuf documentation.
  4. Update SDK and API Examples, Realtime API, or gRPC Debugging.
  5. If protocol behavior changes, update API and Protobuf Evolution.

Operator Workflows

Section titled “Operator Workflows”

Capacity or Performance Issue

Section titled “Capacity or Performance Issue”
  1. Inspect HTTP, WebSocket, database, cache, Provider, livestream, and cluster metrics.
  2. Use Capacity Planning to identify connection, database, Redis, Provider, bandwidth, or storage bottlenecks.
  3. Reduce upstream pressure with Redis, slice cache, member limits, and connection limits.
  4. In multi-replica mode, confirm shared PostgreSQL, Redis, and consistent secrets.
  5. Record version, deployment shape, key metrics, and logs before using Troubleshooting.

Rotate Secrets

Section titled “Rotate Secrets”
  1. Read Security Hardening and Rotation.
  2. Separate directly rotatable tokens from JWT, OPAQUE setup secret, and credential encryption key.
  3. Back up old secrets.
  4. Validate login, Provider decryption, WebSocket, OAuth2, and WebAuthn in a test environment.
  5. Deploy during a quiet window and watch error rates.

Continue Reading

Section titled “Continue Reading”