diff --git a/packages/documentation/docs/for-developers/for-blueprint-developers/ab-playback.md b/packages/documentation/docs/for-developers/for-blueprint-developers/ab-playback.md index 1a78316f770..b051419caa6 100644 --- a/packages/documentation/docs/for-developers/for-blueprint-developers/ab-playback.md +++ b/packages/documentation/docs/for-developers/for-blueprint-developers/ab-playback.md @@ -4,6 +4,10 @@ Prior to 1.50 of Sofie, this was implemented in Blueprints and not natively in Sofie-core ::: +:::tip See Also +For how AB Playback works with lookahead, preroll, and adlibs, see the [Timing and Preparation Guide](./timing-and-preparation.md). +::: + _AB Playback_ is a common technique for clip playback. The aim is to be able to play multiple clips back to back, alternating which player is used for each clip. At first glance it sounds simple to handle, but it quickly becomes complicated when we consider the need to allow users to run adlibs and that the system needs to seamlessly update pre-programmed clips when this happens. diff --git a/packages/documentation/docs/for-developers/for-blueprint-developers/lookahead.md b/packages/documentation/docs/for-developers/for-blueprint-developers/lookahead.md index f1d10c34381..d7db20893c4 100644 --- a/packages/documentation/docs/for-developers/for-blueprint-developers/lookahead.md +++ b/packages/documentation/docs/for-developers/for-blueprint-developers/lookahead.md @@ -1,5 +1,9 @@ # Lookahead +:::tip See Also +For a comprehensive guide on how lookahead works together with preroll, preliminary, transitions, and adlibs, see the [Timing and Preparation Guide](./timing-and-preparation.md). +::: + Lookahead allows Sofie to look into future Parts and Pieces, in order to preload or preview what is coming up. The aim is to fill in the gaps between your TimelineObjects with lookahead versions of these objects. In this way, it can be used to provide functionality such as an AUX on your vision mixer showing the next cut, or to load the next clip into the media player. diff --git a/packages/documentation/docs/for-developers/for-blueprint-developers/part-and-piece-timings.mdx b/packages/documentation/docs/for-developers/for-blueprint-developers/part-and-piece-timings.mdx index 8c2b6e8e694..79ec93d1b08 100644 --- a/packages/documentation/docs/for-developers/for-blueprint-developers/part-and-piece-timings.mdx +++ b/packages/documentation/docs/for-developers/for-blueprint-developers/part-and-piece-timings.mdx @@ -2,6 +2,10 @@ import { PartTimingsDemo } from './_part-timings-demo' # Part and Piece Timings +:::tip See Also +For practical guidance on using preroll, transitions, lookahead together with adlibs, see the [Timing and Preparation Guide](./timing-and-preparation.md). +::: + Parts and pieces are the core groups that form the timeline, and define start and end caps for the other timeline objects. When referring to the timeline in this page, we mean the built timeline objects that is sent to playout-gateway. diff --git a/packages/documentation/docs/for-developers/for-blueprint-developers/timing-and-preparation.md b/packages/documentation/docs/for-developers/for-blueprint-developers/timing-and-preparation.md new file mode 100644 index 00000000000..7f4f9d3a51c --- /dev/null +++ b/packages/documentation/docs/for-developers/for-blueprint-developers/timing-and-preparation.md @@ -0,0 +1,375 @@ +# Timing and Preparation Concepts + +Sofie uses several complementary techniques to ensure smooth, glitch-free playout. Understanding how these work together—especially with adlibs—is crucial for effective blueprint development. + +## Overview + +When content goes to air, multiple timing challenges must be addressed: + +- **Device latency**: Some devices take frames or milliseconds to respond to commands +- **Content loading**: Media needs to be loaded into players before playback +- **Synchronization**: Multiple devices must change state simultaneously for clean transitions +- **Dynamic changes**: Operators triggering adlibs bypasses pre-planned preparation + +Sofie addresses these through a layered approach: + +1. **Lookahead** - Prepares upcoming content during previous parts +2. **Pre-roll** - Compensates for device/content latency +3. **Preliminary** - Sends commands early for timing compensation +4. **Transitions** - Manages smooth handoffs between parts + +## Lookahead: Preparing Future Content + +**Purpose**: Load and prepare content from future parts while earlier content is playing. + +**How it works**: During timeline generation, Sofie searches forward through upcoming parts, finds content that will be needed, and creates "lookahead" timeline objects. These objects can: +- Preload videos into players (using `LookaheadMode.PRELOAD` for background layers) +- Show upcoming content on preview monitors (using `LookaheadMode.WHEN_CLEAR`) +- Assign AB playback servers in advance + +**When it's effective**: +- Planned, pre-programmed content in the rundown +- Following normal part progression (next/take workflow) +- Content that doesn't change due to operator intervention + +**When it's bypassed**: +- **Adlibs**: When operators trigger adlib pieces or actions, lookahead can't predict them +- Rundown changes: Reordering or modifying parts +- Dynamic nexting: Jumping to unexpected parts + +**Example**: A VT clip in Part 5 can be loaded into CasparCG during Part 4, so when Part 5 is taken, the clip is already buffered and ready to play. + +## Pre-roll: Compensating for Latency + +**Purpose**: Start pieces early to compensate for the time devices need before content becomes visible/audible. + +**Set via**: `prerollDuration` property on Pieces (in milliseconds) + +**Common use cases**: + +### Video Playback Latency +Even when a clip is preloaded via lookahead, there's often latency between issuing a PLAY command and frames appearing on SDI: + +```typescript +// VT piece with preroll to compensate for CasparCG playback latency +const vtPiece: IBlueprintPiece = { + externalId: 'vt_clip_001', + name: 'VT: Interview', + prerollDuration: 200, // CasparCG typically needs 5-8 frames (200ms at 25fps) + content: { + timelineObjects: [ + { + id: 'caspar_play', + layer: 'caspar_player_1', + enable: { start: 0 }, + content: { + deviceType: TSR.DeviceType.CASPARCG, + type: TSR.TimelineContentTypeCasparCg.VIDEO, + file: 'interview.mxf' + } + } + ] + } +} +``` + +This ensures that when the vision mixer cuts to the CasparCG input, frames are already flowing. + +### Instant Adlibs with Keyframes +For adlibs that execute immediately (bypassing lookahead), preroll can load content while using keyframes to sync playback: + +```typescript +// vMix internally - loading and playback have different timing needs +const adlibPiece: IBlueprintAdLibPiece = { + externalId: 'adlib_vt_breaking', + name: 'Breaking News VT', + prerollDuration: 1000, // Time needed to load the file + content: { + timelineObjects: [ + { + id: 'vmix_input', + enable: { start: 0 }, + layer: 'vmix_input_1', + content: { + deviceType: TSR.DeviceType.VMIX, + type: TSR.TimelineContentTypeVMix.INPUT, + input: 1, + filePath: 'breaking_news.mp4', + playing: false, // Don't play immediately + }, + keyframes: [ + { + id: 'start_playback', + enable: { start: 1000 }, // Start after loading completes + content: { + playing: true // Now start playback, synced with cut + } + } + ] + } + ] + } +} +``` + +### Latency Variations by Setup + +Different studio configurations require different preroll values: + +| Setup | Typical Preroll | Reason | +|-------|----------------|--------| +| CasparCG → ATEM | 200-300ms | CasparCG playback start latency + cabling | +| vMix internal | 0ms for playback, varies for loading | Play command is instant if loaded; use loading time for preroll | +| vMix → ATEM | 40-80ms | Frame buffering + cabling | +| Quantel server | 0-40ms | Often instant, may need preliminary instead | + +**Key insight from conversation**: "you can assume that a play command is instantaneous (same latency as other commands like Cut)" only when the video player and switcher are the same software (like vMix), because there's no extra cabling and buffering. With external equipment, you must compensate. + +### Lookahead + Preroll Interaction + +**Open question**: When lookahead has successfully preloaded content, can preroll be shortened or eliminated? + +Currently, blueprints must set preroll assuming worst-case (no lookahead). Future enhancements might allow: +- Devices tracking loaded state and adjusting timing +- Conditional preroll based on whether lookahead succeeded +- Blueprint access to lookahead state during timeline generation + +## Preliminary: Early Command Execution + +**Purpose**: Send device commands earlier than their scheduled time to compensate for command processing delays. + +**Set via**: `preliminary` property on commands (in TSR device integrations, not typically in blueprints) + +**Measured in**: Milliseconds before the scheduled timeline time + +**Difference from preroll**: +- **Preroll**: Adjusts when pieces start on the timeline (visible in Sofie UI) +- **Preliminary**: Adjusts when commands are sent to devices (hidden from users) + +**Example use**: Quantel servers might need commands 1000ms early to guarantee frame-accurate execution: + +```typescript +// In TSR device integration (not blueprint code) +{ + command: { + type: QuantelCommandType.PLAYCLIP, + clipId: 123 + }, + preliminary: 1000, // Send command 1 second early + timelineObjId: 'clip_playback' +} +``` + +**When both are needed**: A piece might have both: +- `prerollDuration: 200` (start the piece 200ms early on timeline) +- Commands with `preliminary: 1000` (send those commands 1000ms before their timeline time) +- Net effect: Command sent 1200ms before intended playback point + +## Transitions: Smooth Part Boundaries + +Transitions provide visual continuity when moving between parts: + +### In Transition +Delays new content while playing a transition effect: + +```typescript +const part: IBlueprintPart = { + externalId: 'part_b', + inTransition: { + blockTakeDuration: 1000, // Block takes for 1 second + previousPartKeepaliveDuration: 1000, // Keep Part A alive for 1 second + partContentDelayDuration: 500 // Delay Part B content by 500ms + } +} +``` + +Normal pieces in Part B are delayed by `partContentDelayDuration`, while special pieces with `pieceType: IBlueprintPieceType.InTransition` play during the transition. + +**Interaction with preroll**: Pieces in Part B still need their preroll time, which is added to the transition delay. The previous part extends to accommodate both. + +### Out Transition +Keeps old content playing briefly after a take: + +```typescript +const part: IBlueprintPart = { + externalId: 'part_a', + outTransition: { + duration: 1000 // Keep Part A alive for 1 second after take + } +} +``` + +Pieces with `pieceType: IBlueprintPieceType.OutTransition` play during this extension. + +See [Part and Piece Timings](./part-and-piece-timings.mdx) for detailed timing interactions. + +## Adlibs: The Dynamic Challenge + +**Adlibs** (ad-lib pieces and actions) are operator-triggered content that bypasses normal planning: + +### Why Adlibs Complicate Preparation + +1. **No lookahead**: Can't predict what operators will trigger +2. **Immediate execution**: Often need content on-air within frames +3. **State disruption**: May invalidate lookahead that was prepared for other content + +### Making Adlibs Work + +**Strategy 1: Aggressive preroll** +```typescript +const adlibCamera: IBlueprintAdLibPiece = { + name: 'Camera 3', + prerollDuration: 0, // Vision mixer cuts are instant + content: { /* ... */ } +} + +const adlibVT: IBlueprintAdLibPiece = { + name: 'Breaking News', + prerollDuration: 1500, // Need time to load + buffer + content: { /* ... */ } +} +``` + +**Strategy 2: Expected Packages** +Pre-copy frequently-used adlib media to local storage, so loading is faster: + +```typescript +const adlibPiece: IBlueprintAdLibPiece = { + name: 'Emergency VT', + expectedPackages: [{ + _id: 'emergency_vt_package', + type: ExpectedPackage.PackageType.MEDIA_FILE, + content: { filePath: 'emergency.mxf' }, + // Package manager ensures this is local before rundown activates + }], + content: { /* ... */ } +} +``` + +**Strategy 3: Keep-alive infinites** +Use infinite pieces to keep certain content loaded: + +```typescript +// In a part early in the rundown +const keepAlivePiece: IBlueprintPiece = { + name: 'Preload Common Clips', + lifespan: PieceLifespan.OutOnRundownEnd, // Stays loaded all rundown + enable: { start: 0 }, + content: { + timelineObjects: [ + { + id: 'preload_breaking', + layer: 'caspar_player_2_background', // Using background layer + enable: { while: '1' }, + content: { + deviceType: TSR.DeviceType.CASPARCG, + type: TSR.TimelineContentTypeCasparCg.VIDEO, + file: 'breaking_news_template.mxf', + playing: false // Loaded but not playing + } + } + ] + } +} +``` + +**Strategy 4: Baseline timeline** +Studio baseline can keep devices in a ready state: + +```typescript +// In studio blueprint getBaseline() +return { + timelineObjects: [ + { + id: 'preload_common_graphics', + enable: { while: 1 }, + layer: 'caspar_graphics_background', + content: { + deviceType: TSR.DeviceType.CASPARCG, + type: TSR.TimelineContentTypeCasparCg.TEMPLATE, + templateType: 'html', + name: 'common_lower_third', + useStopCommand: false + } + } + ] +} +``` + +## How Everything Works Together + +### Planned Content Flow +1. **Ingest**: Rundown arrives with VT clips in parts +2. **Expected Packages**: Package Manager copies media to local storage +3. **Lookahead**: During Part A, lookahead finds VT in Part B, creates preload object +4. **Device loading**: CasparCG loads clip into background layer +5. **Take to Part B**: + - Part B timeline starts (with preroll offset) + - CasparCG PLAY command sent (with preliminary offset if configured) + - 200ms later (preroll compensates), video frames reach ATEM + - ATEM cut executes, synchronized with video now flowing +6. **Transition**: In/out transitions provide smooth visual handoff if configured + +### Adlib Flow +1. **Operator triggers**: Camera adlib during VT playback +2. **No lookahead**: Content wasn't predicted +3. **Preroll activates**: If camera switch has `prerollDuration: 0`, happens immediately +4. **Preliminary**: Any ATEM commands might use preliminary timing +5. **Timeline disruption**: Lookahead for Part B may be invalidated +6. **Re-lookahead**: Next timeline generation creates new lookahead based on current state + +### VT Adlib Flow (complex) +1. **Operator triggers**: VT adlib during camera shot +2. **Preroll**: `prerollDuration: 1000` starts piece 1 second early +3. **Load command**: CasparCG LOAD sent immediately (via preliminary timing) +4. **Keyframe**: At `start: 1000`, PLAY command sent +5. **Synchronization**: Vision mixer cut happens at same moment as PLAY +6. **Result**: Clean cut to playing video + +## Best Practices + +### When to Use Each Technique + +| Scenario | Lookahead | Preroll | Preliminary | Transitions | +|----------|-----------|---------|-------------|-------------| +| Planned VT in sequence | ✓ | ✓ | Maybe | Optional | +| Camera cuts | ✗ | Usually 0 | Rarely | Optional | +| Graphics | ✓ | Varies | Rarely | Rarely | +| VT adlib | ✗ | ✓ Required | Maybe | ✗ | +| Part transitions | ✓ | ✓ | Maybe | ✓ | + +### Configuration Guidelines + +1. **Measure your latencies**: Use test patterns and frame counting to determine actual device delays +2. **Set preroll conservatively**: Assume lookahead might fail (it won't for planned content, but keeps adlibs working) +3. **Test adlib paths**: Actually trigger adlibs to verify timing works without lookahead +4. **Consider all device chains**: Latency accumulates through cabling, converters, frame syncs +5. **Document your values**: Comment why specific preroll/preliminary values were chosen + +### Common Pitfalls + +**Relying only on lookahead**: Works great until an adlib breaks the flow. + +**Insufficient preroll for adlibs**: Operators see glitches when triggering unprepared content. + +**Confusing preroll and preliminary**: Preroll is visible in timeline, preliminary is device-internal. + +**Not accounting for loading time**: vMix/CasparCG need time to load files, not just play them. + +**Forgetting keyframe timing**: When using preroll for loading, remember to delay playback start via keyframes. + +## Related Concepts + +See the [Glossary](../glossary.md) for definitions of related terms: + +- **Baseline Timeline** - Studio-level always-on device configuration +- **MakeReady** - Device initialization when rundowns activate +- **Infinite Pieces** - Content that persists across part boundaries +- **Expected Packages** - Media pipeline ensuring files are ready +- **AB Playback** - Automatic player assignment for clip sequences + +## Further Reading + +- [Part and Piece Timings](./part-and-piece-timings.mdx) - Detailed timing mechanics +- [Lookahead](./lookahead.md) - Deep dive into lookahead configuration +- [AB Playback](./ab-playback.md) - Player assignment and management diff --git a/packages/documentation/docs/for-developers/glossary.md b/packages/documentation/docs/for-developers/glossary.md new file mode 100644 index 00000000000..c4dabd6594a --- /dev/null +++ b/packages/documentation/docs/for-developers/glossary.md @@ -0,0 +1,326 @@ +--- +sidebar_position: 20 +--- + +# Glossary + +## Timing and Preparation + +### Adlib (Ad-lib) +Short for "ad libitum" (Latin: "at one's pleasure"). Content that operators can trigger spontaneously during a show, outside the pre-programmed rundown flow. Includes both **adlib pieces** (alternative content like camera shots or clips) and **adlib actions** (scripted operations like "take graphics off"). + +**Key challenge**: Adlibs bypass [lookahead](#lookahead), so [preroll](#preroll-pre-roll) and [expected packages](#expected-package) become critical for smooth execution. + +**Related**: [Timing and Preparation Guide](./for-blueprint-developers/timing-and-preparation.md) + +### Baseline Timeline +Timeline objects defined at the studio level that run continuously, independent of rundown content. Used to establish default device states. + +**Common uses**: +- Setting audio mixer default states +- Configuring vision mixer AUX outputs +- Device routing defaults + +**Defined in**: Studio blueprint's `getBaseline()` method + +**Characteristics**: +- Always enabled: `enable: { while: 1 }` +- Low priority (0-1) so rundown content can override +- Persists across rundowns + +### Expected Package +A declaration in a blueprint that a specific media file or asset is needed for playout. Triggers the Package Manager to copy, transcode, or generate the file. + +**Types include**: +- Media files (video, audio) +- Graphics templates +- Data files + +**Side effects**: Can automatically generate: +- Web previews for UI +- Thumbnail images +- Loudness analysis +- Deep scan metadata + +**Usage**: Critical for ensuring adlib content is ready even though it can't be predicted by lookahead. + +### Infinite Piece +A piece with a `lifespan` that extends beyond its originating part. + +**Lifespans**: +- `WithinPart` - Ends when part ends (normal pieces) +- `OutOnSegmentEnd` - Persists until segment ends +- `OutOnSegmentChange` - Persists until segment changes +- `OutOnRundownEnd` - Persists until rundown ends +- `OutOnRundownChange` - Persists until rundown changes +- `OutOnShowStyleEnd` - Persists until ShowStyle changes + +**Purpose**: Keep content (like graphics, background audio, or loaded media) running across multiple parts without restarting, avoiding flicker and reload delays. + +**Example**: A lower-third graphic that appears in Part 3 and should remain visible through Parts 4, 5, and 6. + +### In Transition +A timing configuration on a part that manages the visual transition when taking **into** that part. + +**Properties**: +- `blockTakeDuration` - How long to prevent additional takes +- `previousPartKeepaliveDuration` - How long to keep previous part playing +- `partContentDelayDuration` - How long to delay new content + +**Effect**: Normal pieces are delayed while special transition pieces (with `pieceType: IBlueprintPieceType.InTransition`) play. + +**Related**: [Out Transition](#out-transition), [Part and Piece Timings](./for-blueprint-developers/part-and-piece-timings.mdx) + +### Lookahead +A Sofie feature that searches future parts/pieces to create timeline objects for preloading or previewing upcoming content. + +**Purpose**: +- Preload media into players before needed +- Show "next" content on preview monitors +- Assign AB playback servers in advance + +**Modes**: +- `NONE` - Lookahead disabled +- `PRELOAD` - Uses secondary device resources (e.g., CasparCG background layer) +- `WHEN_CLEAR` - Fills gaps in timeline + +**Configuration** (per mapping): +- `lookahead` - Which mode to use +- `lookaheadDepth` - Minimum number of future objects to find (default: 1) +- `lookaheadMaxSearchDistance` - Maximum parts to search (default: 10) + +**Limitation**: Cannot predict adlibs or dynamic rundown changes. + +**Related**: [Lookahead Guide](./for-blueprint-developers/lookahead.md), [AB Playback](./for-blueprint-developers/ab-playback.md) + +### MakeReady +A TSR operation that initializes or resets devices to a known good state, typically when a rundown playlist is activated. + +**Common actions**: +- Resetting vision mixers to default state +- Clearing graphics engines +- Resetting audio mixer levels +- Preloading graphics templates + +**Configured in**: Device options (TSR configuration) + +**Triggered**: When rundown playlist activates, or manually via API + +### Out Transition +A timing configuration on a part that manages the visual transition when taking **out of** that part. + +**Property**: +- `duration` - How long to keep this part alive after take + +**Effect**: The part extends beyond the take point, and special pieces with `pieceType: IBlueprintPieceType.OutTransition` play during this extension. + +**Purpose**: Allow visual cleanup or transition effects before the new part fully takes over. + +**Related**: [In Transition](#in-transition), [Postroll](#postroll) + +### Postroll +Duration (in milliseconds) that a piece continues playing **after** its planned end time or after a take out. + +**Set via**: `postrollDuration` property on pieces + +**Purpose**: Allow pieces to complete their content beyond the technical endpoint. Differs from [out transition](#out-transition) in that: +- Out transition keeps **all** pieces playing +- Postroll keeps only **specific** pieces playing + +**Example**: A clip that should play 2 seconds past its formal endpoint to avoid cutting off the final frame. + +**Related**: [Preroll](#preroll-pre-roll), [Part and Piece Timings](./for-blueprint-developers/part-and-piece-timings.mdx) + +### Preliminary +A property on TSR device commands specifying how many milliseconds **before** the scheduled timeline time the command should be executed. + +**Set in**: TSR device integrations (not typically in blueprints) + +**Purpose**: Compensate for command processing delays on devices to achieve frame-accurate execution. + +**Example**: Quantel servers may need commands 1000ms early to guarantee precise timing. + +**Difference from preroll**: +- **Preliminary**: When to send the command (hidden from users) +- **Preroll**: When to start the piece (visible in UI/timeline) + +**Can combine**: A piece with `prerollDuration: 200` might generate commands with `preliminary: 1000`, resulting in commands sent 1200ms before the intended execution point. + +**Related**: [Timing and Preparation Guide](./for-blueprint-developers/timing-and-preparation.md) + +### Preroll (Pre-roll) +Duration (in milliseconds) that a piece needs to prepare its content **before** it should have visible or audible effect. + +**Set via**: `prerollDuration` property on pieces + +**Purpose**: Compensate for: +- Device playback latency (e.g., frames between PLAY command and SDI output) +- Content loading time +- Device stabilization time + +**How it works**: +- Timeline generation adjusts piece start times backward +- Previous part extends to accommodate preroll time +- All pieces in a part get enough time for their individual preroll + +**Common values**: +- Camera cuts: `0ms` (instant) +- CasparCG playback: `200-300ms` (5-8 frames at 25fps) +- File loading: `1000-2000ms` (device/file dependent) + +**Critical for adlibs**: Since lookahead can't prepare adlib content, preroll must be sufficient for worst-case scenarios. + +**Related**: [Timing and Preparation Guide](./for-blueprint-developers/timing-and-preparation.md), [Part and Piece Timings](./for-blueprint-developers/part-and-piece-timings.mdx) + +## Content and Structure + +### Blueprint +JavaScript/TypeScript code bundles that define how Sofie transforms ingest data and controls playout. + +**Types**: +- **System Blueprint** - System-level configuration and migrations +- **Studio Blueprint** - Studio-wide device configuration and baseline +- **ShowStyle Blueprint** - Show-specific content transformation and playout logic + +**Key responsibilities**: +- Transform ingest data into rundowns/segments/parts/pieces +- Generate timeline objects for device control +- Define configuration schemas +- Handle user actions + +### Part +A logical grouping of content within a segment, representing a distinct section of the show (e.g., "Intro", "Interview", "VT Package"). + +**Contains**: Pieces (the actual playout content) + +**Operator interaction**: Parts are the primary unit operators "take" between + +**Timing**: Can have expected duration, auto-next behavior, transitions + +### Piece +The fundamental unit of playout content. Represents a single item to play (camera shot, VT clip, graphic, etc.). + +**Key properties**: +- `externalId` - Unique identifier within the part +- `name` - User-visible label +- `sourceLayerId` - Logical content type +- `outputLayerId` - Destination routing +- `lifespan` - How long it persists +- `enable` - When to start/stop +- `content` - Timeline objects controlling devices + +**Types**: Normal, in-transition, out-transition + +### Rundown +The complete sequence of content for a show, typically received from a newsroom system (NRCS) via MOS or other ingest methods. + +**Structure**: Contains segments, which contain parts, which contain pieces + +**Lifecycle**: Created from ingest, modified by users, executed during playout + +### Segment +A major section of a rundown, typically representing a story or show segment. + +**Contains**: Parts (subdivisions of the segment) + +**Purpose**: Provides logical grouping for navigation and infinite piece scoping + +### ShowStyle +Configuration defining how a particular type of show should behave, including: +- Source and output layer definitions +- Device configuration +- Blueprint logic specific to that show format + +**Examples**: "Daily News", "Sports Show", "Weather Segment" + +### Source Layer +A logical layer representing a type of content (e.g., "Camera", "VT", "Graphics Lower Third"). + +**Purpose**: Abstracts content types from physical device routing + +**Defined in**: ShowStyle configuration + +**Maps to**: Output layers (which map to physical device layers) + +### Timeline Object +Low-level device control instruction that appears on the timeline. + +**Contains**: +- `id` - Unique identifier +- `enable` - When to activate +- `layer` - Which device layer to control +- `content` - Device-specific control data (TSR content) + +**Generated by**: Blueprints (from pieces) or system (lookahead, group wrappers) + +**Executed by**: Timeline State Resolver (TSR) + +## Device Control (TSR) + +### AB Playback +A technique for alternating between video server players to enable seamless back-to-back clip playback. + +**Problem solved**: +- Prevents reloading clips unnecessarily +- Enables instant switching between clips +- Handles dynamic replanning without glitches + +**How it works**: +- Pieces declare `abSessions` requesting a player +- AB resolver assigns sessions to physical players +- Uses lookahead to pre-assign upcoming clips + +**Configuration**: `getAbResolverConfiguration()` in ShowStyle blueprint + +**Related**: [AB Playback Guide](./for-blueprint-developers/ab-playback.md) + +### Mapping +Configuration linking a Sofie layer to a physical device and its control parameters. + +**Key properties**: +- `device` - Which TSR device to control +- `deviceId` - Which physical device +- Device-specific routing (input numbers, layer IDs, etc.) +- `lookahead` - Lookahead mode for this layer +- `lookaheadDepth` - How many future objects to find + +**Defined in**: Studio configuration + +**Used by**: Timeline generation and TSR device control + +### TSR (Timeline State Resolver) +The Node.js library that executes timeline objects by controlling physical broadcast devices. + +**Supported devices**: ATEM, CasparCG, Lawo, vMix, Sisyfos, Quantel, and many more + +**Responsibilities**: +- Maintaining connections to devices +- Converting timeline to device state +- Generating and executing device commands +- Reporting device status + +**Related**: [TSR Repository](https://github.com/Sofie-Automation/sofie-timeline-state-resolver) + +## Data Ingest + +### MOS (Media Object Server) +A standardized protocol for communication between newsroom systems and broadcast automation. + +**Purpose**: Allows NRCS (newsroom computer systems) to send rundown data to Sofie + +**MOS Objects**: Stories, items, metadata that Sofie transforms into rundowns + +**Related**: [MOS Protocol Specification](http://mosprotocol.com/) + +### NRCS (Newsroom Computer System) +The editorial system used by journalists to write scripts and build rundowns. + +**Examples**: Avid iNews, Octopus, ENPS + +**Integration**: Sends data to Sofie via MOS or other protocols + +## See Also + +- [Timing and Preparation Guide](./for-blueprint-developers/timing-and-preparation.md) - Comprehensive guide to lookahead, preroll, preliminary, and transitions +- [Blueprint Developer Introduction](./for-blueprint-developers/intro.md) +- [Data Model](./data-model.md)