Speech Packs
Speech packs are collections of templates that drive cabin announcements during flights. Each pack contains one or more templates tied to specific flight phases. Templates can be either text-based (converted to audio using ElevenLabs text-to-speech) or audio-based (using a pre-recorded audio file). This allows virtual airlines to deliver realistic, phase-appropriate PA announcements to pilots through ACARS clients.
Backoffice path: backoffice/speech-packs
Available to roles: System Administrator, Administrator
Pack Structure
Each speech pack has the following top-level fields:
| Field | Description |
|---|---|
| Name | Display name for the pack (e.g., "Standard English PA", "Lufthansa Regional") |
| Description | Optional notes about the pack's intended use or audience |
| Active | Toggle to enable or disable the entire pack |
A pack contains one or more templates, each defining a single announcement that plays at a specific point during the flight.
Template Editor
The template editor is organized into tabs by flight phase. Each of the 12 trigger phases (Gate Departure, Pushback, Taxi, etc.) has its own tab. To add a template for a specific phase, click on that phase's tab and then click "Add Template". The trigger phase is set automatically based on the active tab.
Each tab displays a badge showing the number of templates configured for that phase, making it easy to see which phases have announcements at a glance.
When editing an existing speech pack, templates are autosaved when switching between tabs, so you can freely move between phases without losing your work.
Templates
Each template within a speech pack configures a single announcement. Templates support two types:
- Text (default) -- The announcement body is written as text with optional template variables and synthesized into audio via ElevenLabs TTS.
- Audio -- A pre-recorded audio file is uploaded directly. No TTS generation occurs; the uploaded file is used as-is (with an optional PA effect applied).
Template Fields
| Field | Description |
|---|---|
| Type | Either Text or Audio. Determines whether the template uses TTS generation or a pre-recorded audio file |
| Trigger phase | Automatically set by the active tab in the template editor (see table below) |
| Voice role | Either CAPTAIN or FLIGHT_ATTENDANT -- determines which persona delivers the announcement |
| Voice profile | Links to a Voice Profile that defines the ElevenLabs voice and its TTS parameters. Required for text templates; not required for audio templates |
| Speech language override | Optionally overrides the voice profile's default Speech Language for this template |
| Template text | The announcement body, which may include template variables (see below). Required for text templates; not used for audio templates |
| Audio file | The uploaded pre-recorded audio file (MP3, WAV, M4A, AAC — max 10 MB). The file is uploaded and processed immediately when selected, so you can continue editing the pack without waiting. Only used for audio templates |
| Apply PA effect | Whether to apply the PA microphone effect (bandpass filter, compression, echo) to the uploaded audio. Defaults to enabled. Only applies to audio templates |
| Sort order | Numeric ordering when multiple templates share the same trigger phase |
| Active | Toggle to enable or disable this individual template |
Trigger Phases
Templates can be triggered at these flight phases:
| Phase | Identifier | When It Fires |
|---|---|---|
| Gate Departure | gate_departure | Before pushback, while still at the gate |
| Pushback | pushback | During pushback from the gate |
| Taxi | taxi | During taxi to the runway |
| Climb Out | climb_out | After takeoff, during initial climb (60s after entering climb zone) |
| Passing 10,000 | passing_10000 | Climbing through 10,000 ft after takeoff |
| Cruise | cruise | Upon reaching cruise altitude |
| Descend | descend | When descent begins near destination |
| Descending 10,000 | descending_10000 | Descending through 10,000 ft on approach |
| Final Approach | final_approach | On final approach to the runway |
| After Landing | after_landing | After touchdown and rollout |
| Gate Arrival | gate_arrival | Upon arriving at the destination gate |
| Alternate Declared | alternate_declared | When the pilot declares a diversion to an alternate airport |
Template Variables
Template text supports dynamic variables that are resolved at generation time using actual flight data:
| Variable | Resolves To | Example |
|---|---|---|
{salute} | Time-of-day greeting based on the speech language's salute configuration | "Good morning" |
{flight_number} | Flight number with digits spoken as words (localized) | "one two three four" |
{destination} | Arrival airport city name | "London" |
{origin} | Departure airport city name | "Frankfurt" |
{airline} | Airline name | "Lufthansa" |
{aircraft_type} | Fleet or aircraft type name | "Airbus A320" |
{captain} | Pilot-in-command name | "Captain Mueller" |
{callsign} | ATC callsign | "Speedbird 42" |
Example template text:
{salute}, ladies and gentlemen. This is your captain speaking. Welcome aboard {airline} flight {flight_number}
with service from {origin} to {destination}. We'll be flying in a {aircraft_type} today.
Please ensure your seatbelts are fastened and your tray tables are in the upright position.
Assignment and Priority Resolution
Speech packs are not global by default. They must be explicitly assigned to one or more of the following entities:
- Airlines -- applies to all flights operated by the airline
- Fleets -- applies to all aircraft in the fleet
- Subfleets -- applies to all aircraft in the subfleet
- Aircraft -- applies to a specific tail number
- Airports -- applies in either a departure or arrival context
When multiple speech packs apply to a given flight (e.g., one assigned to the airline and another to the specific aircraft), the system resolves conflicts using a priority hierarchy. The most specific assignment wins:
| Priority | Assignment Level | Description |
|---|---|---|
| 1 (highest) | Aircraft | Pack assigned to the specific tail number |
| 2 | Arrival Airport | Pack assigned to the arrival airport |
| 3 | Departure Airport | Pack assigned to the departure airport |
| 4 | Subfleet | Pack assigned to the aircraft's subfleet |
| 5 | Fleet | Pack assigned to the aircraft's fleet |
| 6 (lowest) | Airline | Pack assigned to the operating airline |
This overlay system allows you to set a baseline pack at the airline level and then override specific announcements for particular airports, aircraft types, or individual tail numbers. For example, you might have a standard English pack for the airline but assign a bilingual pack to aircraft operating into Tokyo Narita.
Audio Generation and Caching
When a template's text (after variable substitution) is sent to ElevenLabs for synthesis, the resulting audio is cached using a SHA-256 hash of the rendered text. This means:
- If the same exact text has been generated before, the cached audio is reused and ElevenLabs is not called again.
- Changing any variable value (different flight number, different destination) produces a different hash and triggers new audio generation.
- Editing the template text itself will also produce new audio on next use.
Audio Format and PA Effect
Generated audio fragments are stored as MP3 files. An optional PA microphone effect can be applied to simulate a realistic cabin PA system. This effect chain includes:
- Bandpass filter -- rolls off low and high frequencies to emulate a cabin speaker
- Compression -- levels out volume peaks and valleys
- Echo -- adds subtle reverb typical of aircraft cabin acoustics
Delivery to Clients
Cached audio is delivered to ACARS clients via the API endpoint:
GET /api/acars/sound
All fragments for a given flight phase (including silence gaps between sentences and templates) are combined into a single MP3 file using FFmpeg. The client receives one audio URL per phase and plays it as a single, seamless announcement.
Usage Tips
- Start with a single pack assigned at the airline level to cover all flights, then add specialized packs as needed.
- Use the sort order field to sequence multiple announcements within the same flight phase (e.g., captain welcome followed by flight attendant safety briefing at gate departure).
- Disable individual templates with the active toggle rather than deleting them -- this preserves your work if you want to re-enable them later.
- The speech language override on individual templates is useful for bilingual announcements: create two templates for the same phase, one in each language, with appropriate sort ordering.
- Monitor your ElevenLabs usage, since each unique text rendering consumes API credits. The SHA-256 caching helps minimize redundant calls.