Alana

01 / Context

The problem behind the project

Rendering a program, encoding it, publishing it, and recording it have different failure modes. A failure in one output should not restart every other part of a broadcast.

A television program is more than an encoder process. It combines rendered graphics, audio, optional low-latency return video, recordings, and public delivery. These outputs need clear ownership so a failed recorder or destination does not unnecessarily take the entire program off air.

Alana replaces the earlier description of this project as an OBS container. Its responsibility is to render Alcántara’s composed Program headlessly and supervise publication, while Palazzo handles radio and Croccante handles public relay continuity.

02 / Implementation

Design and implementation

I build the runtime supervision and explicit start/stop lifecycle that connect program rendering to broadcast delivery.

I built the runtime around Chromium, a virtual display, PulseAudio, FFmpeg, and an optional LiveKit publisher. Browser and audio capture are shared inputs; output encoders, progress tracking, watchdogs, restart budgets, and health state are isolated by output.

The private control service persists requested and actual lifecycle state. Start first establishes local readiness, then obtains an exact matching Croccante acknowledgement. Stop waits for the relay’s acknowledgement before removing local output. A downstream failure remains visible as degraded state rather than being turned into an apparently successful Stop.

I also added an independent recorder for the composed program. Closed Matroska segments have checksums and media manifests; finalization verifies them and remuxes a final MP4 without another encode. Disk quotas, free-space reserves, restart limits, and recording failures affect the recorder rather than the live program.

03 / Architecture

Architecture and workflow

1. 01

   Render one program

   A program-scoped runtime opens the authorized renderer in Chromium and captures its display and mixed audio.

2. 02

   Publish isolated outputs

   RTMP encoders and the optional LiveKit leg have separate process supervision and recovery. A failed leg cannot restart the others.

3. 03

   Coordinate public delivery

   Alana passes an immutable destination selection and prepared filler version to Croccante, then checks the returned version, hash, count, and IDs.

4. 04

   Record separately

   An explicitly started recorder consumes the composed display and audio, persists closed segments, and produces a verified final artifact after Stop.

5. 05

   Reconcile after restart

   Durable lifecycle state restores intent; current process and relay observations determine whether the requested program is actually running.

04 / Approach

Engineering decisions

05 / Evidence

Evidence and outcomes

The repository documents command replay, out-of-order sequences, downstream acknowledgement mismatches, process stalls, and restart reconciliation as explicit runtime cases. Recording checks cover segment validation, finalization, bounded retries, and low-disk conditions.

A completed recording requires both valid audio/video streams and a checksum-verified final file. A requested operation or a finalizing file is not advertised as reusable media. This contract is also consumed by Alcántara’s recording controls and Broadway’s excerpt-draft work.

Source and technical notes