# Channel Architecture

## Channel Entity

Defined in `ErsatzTV.Core/Domain/Channel.cs`. Key fields:

- **Identity**: `Number` (e.g., "1", "2.1"), `Name`, `UniqueId` (GUID for M3U/XMLTV)
- **Encoding**: `FFmpegProfileId` — video/audio codec, bitrate, resolution, hardware acceleration
- **Streaming**: `StreamingMode` (TransportStream, HLS Direct, HLS Segmenter, TS Hybrid)
- **Behavior**: `PlayoutMode` (Continuous vs OnDemand), `IdleBehavior` (StopOnDisconnect vs KeepRunning)
- **Visual**: `WatermarkId`, `FallbackFillerId`, artwork (logos)
- **Mirroring**: `PlayoutSource` (Generated vs Mirror) — a mirror channel copies another with optional time offset
- **Display**: `Group`, `Categories`, `ShowInEpg`, `IsEnabled`
- **Audio/Subtitle defaults**: preferred language codes, subtitle mode

## Content Sources

Channels get content through a **Playout** → **ProgramSchedule** → **ProgramScheduleItem** chain.

### Collection Types

| Type | Description |
|------|-------------|
| `Collection` | Manual grouping of media items with custom playback order |
| `MultiCollection` | Aggregate of collections + smart collections |
| `SmartCollection` | Query-based (Lucene.Net) dynamic filtering |
| `Playlist` | Ordered items with per-item config (count, fillers, playback order) |
| `TelevisionShow` / `TelevisionSeason` | Structured TV hierarchy |
| `Movie`, `Episode`, `MusicVideo`, `OtherVideo`, `Song`, `Image` | Individual media items |
| `RerunCollection` | Wraps any collection with separate first-run/rerun playback orders |
| `SearchQuery` | Dynamic results from a search |
| `RemoteStream` | External stream URLs |

### Media Sources

Media items are imported from configured libraries (Jellyfin, Plex, Emby, or local filesystem). Each source type has its own entity variants (e.g., `JellyfinMovie`, `PlexEpisode`).

## Scheduling

### Schedule Kinds

- **Classic**: Traditional ProgramSchedule with items — the most common
- **Block**: Template-based block scheduling
- **Sequential**: Strict sequential ordering
- **Scripted**: External script-driven playout
- **ExternalJson**: Playout defined by external JSON file

### Schedule Item Types

Each `ProgramScheduleItem` is one of four concrete types:

1. **One** — Play exactly 1 item per cycle
2. **Multiple** — Play N items (fixed count, collection size, or playlist item size)
3. **Duration** — Fill a time window (with tail mode: none, offline, slate, or filler)
4. **Flood** — Play items continuously until the next fixed-start item

Items can have `StartType` of Fixed (anchored to clock time) or Dynamic (follows previous item).

### Playback Orders

`Chronological`, `Random`, `Shuffle`, `ShuffleInOrder`, `MultiEpisodeShuffle`, `SeasonEpisode`, `RandomRotation`, `Marathon` (group by show/season/artist/album/director).

### Filler System

`FillerPreset` defines content to fill gaps. Each schedule item can have:
- **PreRoll** — before main content
- **MidRoll** — during (chapter breaks)
- **PostRoll** — after main content
- **Tail** — pad remaining time in a duration block
- **Fallback** — channel-level default when nothing else available

Filler modes: Duration, Count, Pad (to nearest minute), RandomCount.

### Alternate Schedules

`ProgramScheduleAlternate` overrides the main schedule for specific days of week, days of month, months of year, or date ranges. Useful for seasonal programming or weekend variations.

## Playout Pipeline

```
Channel
└── Playout
    ├── ProgramSchedule
    │   └── ProgramScheduleItems (One|Multiple|Duration|Flood)
    │       └── Content source (Collection, Playlist, SmartCollection, etc.)
    ├── PlayoutItems (generated — the actual timeline)
    │   └── MediaItem + start/finish times + filler kind + watermarks
    ├── PlayoutGaps (time periods with no content)
    └── ProgramScheduleAlternates (day/date overrides)
```

The scheduling engine (`ErsatzTV.Core/Scheduling/`) resolves schedule items into concrete `PlayoutItem` entries with precise start/finish times. Each `PlayoutItem` references a specific `MediaItem` and includes trim points (`InPoint`/`OutPoint`), filler classification, and per-item audio/subtitle overrides.

## Watermarks

`ChannelWatermark` supports modes: Permanent, Intermittent, OpacityExpression. Image sources: custom upload, channel logo, or built-in resource. Positioned with percentage-based margins and z-index.

Note: `ChannelLogoGenerator.GenerateChannelLogoUrl()` hardcodes `localhost` for watermark logo fetching — see issue #1 for details.