Skip to main content

Channel Stream Organiser (CSO)

The Channel Stream Organiser (CSO) is Headendarr's stream orchestration pipeline. It sits between client requests and upstream sources to provide consistent playback behaviour, source-capacity checks, and controlled failover/remux handling.

What CSO does​

CSO is responsible for:

  • Selecting eligible sources for a channel and applying source order/failover rules.
  • Enforcing source connection limits before and during playback.
  • Running a shared ingest pipeline and fan-out output sessions for active clients.
  • Applying profile-based output behaviour (for example remux/transcode targets).
  • Serving both live channel playback and CSO-managed VOD playback paths.
  • Returning explicit unavailable/limit responses when capacity is exhausted.

Core CSO paths​

  • Channel playback path:
    • /tic-api/cso/channel/<channel_id>
  • Per-source stream gate path:
    • /tic-api/cso/channel_stream/<stream_id>
  • HLS output variants (when an HLS profile is used):
    • /tic-api/cso/channel/<channel_id>/hls/<connection_id>/index.m3u8
    • /tic-api/cso/channel_stream/<stream_id>/hls/<connection_id>/index.m3u8

For complete endpoint coverage, see Connectivity Endpoints.

How CSO works at runtime​

At a high level:

  1. A client request enters a CSO route.
  2. CSO resolves the effective profile/routing mode.
  3. CSO starts or joins an ingest session for the selected source.
  4. CSO starts or joins an output session for the requested profile/container.
  5. The client is attached to that output session (with queue/backpressure handling).
  6. On disconnect/idle/error, CSO tears down client/output/ingest state as needed.

This design allows multiple local clients to share upstream work while preserving source-limit behaviour.

These settings control where CSO is used:

  1. Use CSO for combined playlists, XC, & combined HDHomeRun

    • Applies to combined endpoints.
    • Enables CSO-centric routing semantics for combined outputs.

  2. Route per-source playlists & per-source HDHomeRun via TVHeadend

    • Moves per-source playlist/HDHR client traffic through TVHeadend-facing paths.
    • Useful when TVHeadend is your primary stream-facing service.

  3. TVHeadend Settings -> Stream Buffer = CSO

    • Routes TVHeadend mux pulls through CSO stream paths.
    • Improves consistency of buffering/limit handling for mixed-client setups.

See Application Settings and TVHeadend Integration for exact setting definitions.

Profiles and output behaviour​

CSO honours profile arguments where supported and falls back to defaults when profiles are missing/unsupported.

  • Remux/copy profiles include default, mpegts, matroska, mp4, webm, and hls.
  • Audio-only transform profiles include aac-mpegts, aac-matroska, aac-mp4, and aac-hls.
  • Video/audio transform profiles include H.264, H.265, VP8, and AV1 variants such as h264-aac-mpegts, h264-aac-hls, h265-aac-mp4, vp8-vorbis-webm, av1-aac-hls, av1-opus-hls, and av1-opus-webm.
  • AV1-over-HLS is exposed through av1-aac-hls and av1-opus-hls.
  • TVHeadend-only profile semantics: tvh

Profile details and endpoint-level behaviour are documented in Connectivity Endpoints.

CSO VOD playback​

CSO also backs the browser-oriented VOD preview/playback routes.

  • Curated VOD previews resolve to /tic-api/cso/vod/<movie|series>/<item_id>.
  • Upstream/admin previews resolve to /tic-api/cso/vod/upstream/<source_id>/<movie|series>/<item_id>.
  • The initial preview response is designed to start playback quickly without blocking on a full media probe.
  • Source duration, resolution, and richer playback profile options are then filled in asynchronously once probe results are ready.

Failure and capacity behaviour​

When source capacity is exhausted or playback cannot start:

  • CSO blocks over-subscription instead of silently allowing extra upstream sessions.
  • Client playback requests can receive unavailable/limit outcomes (depending on route/profile behaviour).
  • In mixed-client deployments, this makes source limit enforcement explicit and predictable.

VOD 24/7 channels through CSO​

VOD 24/7 channels also use CSO, but with a different runtime shape from a normal live channel.

  • The channel does not keep a permanent upstream live stream open while idle.
  • When tuned, CSO resolves the programme that should be airing at that moment and starts playback from the correct in-programme offset.
  • Headendarr then tries to hand playback over to local cached media as early as possible so upstream capacity is released quickly.
  • The next scheduled programme is pre-downloaded 2 minutes ahead of time.
  • Around 20 seconds before the boundary, CSO also prepares the next segment and pre-buffers it to reduce visible transition gaps.
  • The ingest side transcodes VOD 24/7 playback into a stable single-video, single-audio MPEG-TS feed, and the output side remuxes that feed when the requested profile already matches.
  • VOD 24/7 channels support both the direct CSO stream route and the CSO HLS route, using the same stitched ingest path underneath.

For the full behaviour and configuration details, see VOD 24/7 Channels.

When to use CSO-centric routing​

Prefer CSO-centric paths when:

  • You need strict source-limit enforcement across mixed client types.
  • You want predictable channel failover and stream orchestration.
  • You want consistent routing behaviour for combined outputs and TVHeadend mux pulls.
  • You want stronger client observability (start/stop visibility) and more reliable stream audit coverage instead of opaque direct-to-source client pulls.