Skip to main content
GET
Stream TV Channel Feed

Overview

Stream the events of the current TV game for a specific channel. This endpoint uses Server-Sent Events (SSE) to push updates in real-time as moves are played.

Endpoints

Stream Default Channel (Best)

Streams the “Best” channel (top-rated games).

Stream Specific Channel

Streams a specific TV channel.

Authentication

No authentication required. These are public endpoints.

Parameters

string
The TV channel to stream. If omitted, defaults to “best”.Available channels:
  • best - Top Rated (2150+ standard games)
  • bullet - Bullet games
  • blitz - Blitz games
  • rapid - Rapid games
  • classical - Classical games
  • chess960 - Chess960 variant
  • kingOfTheHill - King of the Hill
  • threeCheck - Three-check
  • antichess - Antichess
  • atomic - Atomic
  • horde - Horde
  • racingKings - Racing Kings
  • crazyhouse - Crazyhouse
  • ultraBullet - UltraBullet
  • bot - Bot games
  • computer - Computer games
boolean
default:"false"
Enable backwards compatibility mode. When true, uses Server-Sent Events format. When false (default), uses newline-delimited JSON (NDJSON).

Response Format

NDJSON Format (Default)

By default, the stream returns newline-delimited JSON. Each line is a complete JSON object representing a game event.

SSE Format

When bc=true, the stream uses Server-Sent Events format with text/event-stream content type.

Example Requests

cURL - Default Channel
cURL - Specific Channel
cURL - SSE Format
JavaScript - NDJSON
JavaScript - EventSource (SSE)
Python

Event Types

The stream emits various game-related events: When a new game becomes featured on the channel:

Move Event

When a move is played:

Game End Event

When the featured game ends:

Response Fields

string
Event type: featured, ply, end, etc.
object
Event data - structure varies by event type

Connection Management

  • The stream is kept alive with periodic keep-alive messages
  • When a featured game ends, a new game from the channel will automatically be featured
  • Connections should be resilient to temporary disconnections and reconnect automatically
  • Games are refreshed based on activity - inactive games are replaced

Rate Limiting

  • Persistent connections are allowed but limited per IP address
  • Maximum of 4 concurrent streams per IP for standard users
  • Do not poll this endpoint - it’s designed to be streamed continuously

Channel Selection Criteria

Each channel selects games based on specific criteria:
  • Rating filters: Most channels require minimum ratings (e.g., Best: 2150+, Blitz: 2000+)
  • Time controls: Speed-based channels filter by game time control
  • Variants: Variant channels show only that specific chess variant
  • Recency: Games must have recent moves (freshness varies by channel)
  • Bot exclusion: Most channels exclude bot games (except the Bot channel)

Notes

  • The stream automatically switches to new games when the current one ends or becomes stale
  • Not all channels have active games at all times
  • The default channel (“best”) typically has the most consistent availability
  • Use NDJSON format (default) for simpler parsing in modern applications

Source Code Reference

  • Controller: app/controllers/Tv.scala:92-108
  • Routes: conf/routes:43-44