Starting and stopping

Engines only transcode while they run: you start them when you go live and stop them when you are done. You can start and stop each engine on its own, or all engines of a channel at once, which is what most workflows do.

Engine states

From the moment you start it until it has stopped again, an engine goes through these states:

State	Meaning
stopped	The engine is not running. This is the only state from which it can be started.
deploying	The start request has been accepted.
provisioning	Compute is being allocated for the engine and its software is being loaded.
starting	The engine is booting.
waiting	The engine is running and waiting for the contribution from its ingest.
ingesting	The engine is receiving the contribution and preparing its outputs.
playing	The engine is producing all its outputs: the stream is available to viewers.
stopping	The engine is shutting down, after a stop or force stop.
error	The engine ran into an error. Stop it before you start it again.

A started engine goes from deploying through provisioning and starting to waiting, then to ingesting and playing as soon as the contribution arrives. If the contribution stops while the engine is playing, the engine goes back to waiting until the contribution resumes.

The status of a channel is derived from its engines, and the most active engine state wins: a channel with one playing and one stopping engine is playing. A channel is only stopping once all its engines are stopping or stopped, and a channel without engines is ready.

Starting

Starting an engine deploys it in its region and begins its transcoding time, even before a contribution is connected. Starting a channel starts all its engines that are stopped, as well as its RTSP pull ingests; engines in any other state are left as they are.

Auto-stop timeout

An engine that stays waiting for longer than the channel's timeout is stopped automatically, so an engine without contribution does not keep running. The timeout counts from the moment the engine started waiting, both after a start and after the contribution dropped. It defaults to 3600 seconds (1 hour); set it to 0 to never stop automatically. In the dashboard, this is the Auto-stop timeout of the channel.

Stopping

You can stop an engine, or all engines of a channel at once, in two ways:

• Stop ends the stream and then shuts the engine down gracefully: players stop playback at the end of the stream. This is the right choice when you are done streaming.
• Force stop tears the engine down immediately, without ending the stream: OptiView Player falls back to another engine of the distribution, or playback fails when there is none. Use it to move viewers over to a backup engine, when the engine has to be gone at once, or to cut short a stop that is still in progress.

Either way, the engine's transcoding time stops counting as soon as the stop is requested, not when the engine reaches stopped.

Stop

A stop ends the stream before the engine goes away. The engine closes its playlists (an HLS media playlist gets an EXT-X-ENDLIST tag), so players reach the end of the stream instead of running into a playback error. The engine then shuts down: it reports stopping for about 10–20 seconds, then stopped.

Because the stream ends cleanly, players treat it as finished: they do not fall back to another engine of the distribution. To take one engine of a redundant setup out of service while viewers keep watching, force stop it instead.

Schedulers and the auto-stop timeout stop engines the same way.

Force stop

A force stop skips the graceful shutdown: the engine is torn down right away, without closing its playlists. The engine reports stopping for a few seconds, then stopped.

From the moment of the force stop, playlist requests for the engine intentionally start failing, so players detect that the engine is gone:

• With redundancy: when the distribution has other engines, OptiView Player falls back to the next available engine, as in any failover. Viewers may see a brief interruption but keep watching.
• Without redundancy: when the engine was the only one of the distribution, playback fails.

A third-party player that loads the HLS URL of the distribution directly (see Other HLS player) may not fall back to another engine: for its viewers, playback may fail even with redundancy.

A force stop works from any state except stopped, including while the engine is still stopping after a regular stop.

Rules

• An engine can only be started again once it is stopped. Starting an engine in any other state fails with 409 already_playing. Because starting a channel skips engines that are still stopping, wait until the channel is stopped before you start it again.
• Stopping an engine that is already stopping force stops it. Calling stop a second time on an engine or a channel therefore has the same effect as a force stop.
• An engine in error is always force stopped. It has no stream left to end, so a stop tears it down right away.
• Stopping or force stopping a stopped engine fails with 409 already_stopped.
• Starting or stopping a channel covers the whole channel. It does the same to all its engines and to its RTSP pull ingests.

API

Action	Engine	Channel
Start	POST /v2/engines/{engineId}/start	POST /v2/channels/{channelId}/start
Stop	POST /v2/engines/{engineId}/stop	POST /v2/channels/{channelId}/stop
Force stop	POST /v2/engines/{engineId}/force-stop	POST /v2/channels/{channelId}/force-stop

All of them return 204 as soon as the request is accepted; the engines then start or shut down in the background. Follow their progress through the status of the engine or channel, or through webhooks.

API example — Start a channel

POST https://api.theo.live/v2/channels/{channelId}/start

curl -X POST https://api.theo.live/v2/channels/ch_abc123/start \
  -H "Authorization: Basic $AUTH"

API example — Stop a channel

POST https://api.theo.live/v2/channels/{channelId}/stop

curl -X POST https://api.theo.live/v2/channels/ch_abc123/stop \
  -H "Authorization: Basic $AUTH"

API example — Force stop a channel

POST https://api.theo.live/v2/channels/{channelId}/force-stop

curl -X POST https://api.theo.live/v2/channels/ch_abc123/force-stop \
  -H "Authorization: Basic $AUTH"

API example — Start an engine

POST https://api.theo.live/v2/engines/{engineId}/start

curl -X POST https://api.theo.live/v2/engines/eng_ghi789/start \
  -H "Authorization: Basic $AUTH"

API example — Stop an engine

POST https://api.theo.live/v2/engines/{engineId}/stop

curl -X POST https://api.theo.live/v2/engines/eng_ghi789/stop \
  -H "Authorization: Basic $AUTH"

API example — Force stop an engine

POST https://api.theo.live/v2/engines/{engineId}/force-stop

curl -X POST https://api.theo.live/v2/engines/eng_ghi789/force-stop \
  -H "Authorization: Basic $AUTH"

Dashboard

In the dashboard, you start and stop a whole channel from the channel details page or the channels table, and a single engine from its card on the channel details page.

• Start: Start channel on the channel details page, Start all engines in the channels table and the start button of an engine each ask you to confirm before they start.
• Stop: every stop button opens a dialog that lets you choose between a stop and a force stop. Stop channel on the channel details page, and Stop all engines in the channels table, open the Stop all engines dialog, with Stop all and Force stop all. The stop button of an engine opens the Stop engine dialog, with Stop and Force stop.

While an engine or a channel is stopping, the graceful option is gone: its stop button becomes Force stop (Force stop channel on the channel details page, Force stop all engines in the channels table), and the dialog only offers the force stop. The start button of an engine only returns once the engine is stopped.

Webhooks

Every state change of an engine sends the matching engine webhook event: engine.deploying when a start is accepted, then engine.provisioning, engine.starting, engine.waiting, engine.ingesting and engine.playing as the engine reports them. The events the engine reports carry its previousStatus in data, and engine.error also carries an errorMessage. Starting a channel also sends channel.deploying when the start is accepted.

Each way of stopping sends engine.stopping and engine.stopped at different moments:

Stopping	engine.stopping	engine.stopped
Stop	When the stop is accepted	Once the engine is torn down, about 10–20 s later
Force stop	When the force stop is accepted	Once the engine is torn down, a few seconds later
Stop or force stop of an engine that is stopping	Not sent again	Once the engine is torn down, a few seconds later
Stop of an engine in error	When the stop is accepted	Once the engine is torn down, a few seconds later

channel.stopped is sent when a stop or force stop of the channel is accepted, while its engines may still be shutting down. To know when an engine is gone, wait for its engine.stopped.