Channel Templates (built-in + custom) bundling technical/behavioral defaults #64

Closed
opened 2026-07-01 23:01:55 +02:00 by timothy · 2 comments
Owner

Part of #62 (Create Channel backend prerequisites). Directly satisfies a #59 goal ("better defaults and templates").

Goal

A Channel Template entity that bundles the clunky technical/behavioral settings so most channels need zero manual config.

Scope

  • Bundle: FFmpeg/transcode profile, fillers (pre/mid/post-roll), interleaving, subtitle behavior, shuffle default, playout defaults, and other repeated setup choices.
  • Built-in templates shipped out of the box (e.g. "Standard", "Music videos") and user-saved custom templates.
  • A default template is pre-selected in the create flow.
  • Templates are referenced by the composite create endpoint and overridable via the "Advanced" section.

Notes

  • New domain entity + migrations (both SQLite and MySql providers).
  • Consider whether existing FFmpegProfile / FillerPreset entities are composed into a template vs. duplicated.
Part of #62 (Create Channel backend prerequisites). Directly satisfies a #59 goal ("better defaults and templates"). ## Goal A **Channel Template** entity that bundles the clunky technical/behavioral settings so most channels need zero manual config. ## Scope - Bundle: FFmpeg/transcode profile, fillers (pre/mid/post-roll), interleaving, subtitle behavior, shuffle default, playout defaults, and other repeated setup choices. - **Built-in templates** shipped out of the box (e.g. "Standard", "Music videos") **and** user-saved custom templates. - A default template is pre-selected in the create flow. - Templates are referenced by the composite create endpoint and overridable via the "Advanced" section. ## Notes - New domain entity + migrations (both SQLite and MySql providers). - Consider whether existing FFmpegProfile / FillerPreset entities are composed into a template vs. duplicated.
timothy added a new dependency 2026-07-02 01:08:42 +02:00
Author
Owner

Design approach before coding

I read the issue body plus CLAUDE.md / docs/contributing.md and surveyed the existing channel, schedule, playout, FFmpeg, filler, seeding, and REST API patterns.

Entity shape / composition decision

I will model ChannelTemplate as a first-class domain entity that composes existing entities by reference instead of duplicating their values:

  • FFmpegProfileId required, referencing the chosen transcode profile.
  • Optional WatermarkId, FallbackFillerId, PreRollFillerId, MidRollFillerId, PostRollFillerId referencing the existing watermark/filler preset entities.
  • The filler IDs will validate against the matching FillerKind where applicable.
  • This keeps template changes aligned with existing profiles/presets and avoids a second copy of FFmpeg/filler configuration that could drift from the source entities.

Templates will be applied at channel creation time by #63, not live-linked to channels. So deleting or editing a template will not break existing channels created from it. #63 can take templateId plus Advanced overrides, resolve the template, and stamp the resulting channel/schedule/playout values into the normal channel creation flow.

Bundle scope

Core bundle fields I plan to persist now:

  • Identity: Name, Description, IsSystem.
  • Technical channel defaults: FFmpegProfileId, StreamingMode, TranscodeMode, optional WatermarkId, optional FallbackFillerId.
  • Playback/source defaults: PlayoutSource, PlayoutMode, IdleBehavior, StreamSelectorMode, StreamSelector, audio preference fields.
  • Subtitle/music-video defaults: PreferredSubtitleLanguageCode, SubtitleMode, MusicVideoCreditsMode, MusicVideoCreditsTemplate, SongVideoMode.
  • Schedule/playout defaults for #63: ShuffleScheduleItems, RandomStartPoint, FixedStartTimeBehavior, optional PreRollFillerId, MidRollFillerId, PostRollFillerId.

I am intentionally not adding per-item graphics/deco/watermark lists or every schedule-item tail field in this slice. The entity should make #63 and the SPA create flow easy without duplicating the whole schedule editor. If review shows a necessary missing tail field, I will call it out as follow-up rather than expanding the model indefinitely.

This shape should also ease #68 later: resume/bookmark behavior can be added as new per-channel/default behavior flags without changing the composition-by-reference decision.

Built-ins and default selection

I will follow DbInitializer precedent used for default FFmpeg/profile/config values:

  • Seed built-in templates during startup after default FFmpeg profile exists.
  • Built-ins have IsSystem = true and cannot be deleted.
  • Seeding will be idempotent by stable built-in name/key and should not clobber user-created templates. For built-ins, the initializer can create missing rows and leave existing rows alone unless a minimal repair is needed for required references.
  • Default template selection will be stored with a new ConfigElementKey (e.g. channel_templates.default_template_id) so the create flow can preselect it without making IsDefault mutually exclusive state across rows.
  • Initial built-ins: Standard as default, plus Music videos with music-video-friendly defaults.

REST API surface

Under /api/channel-templates, using the existing #2a API conventions (ApiResults, NotFoundError, request DTOs, route Name = ..., ProblemDetails metadata, OpenAPI contract tests):

  • GET /api/channel-templates (GetChannelTemplates) returns templates, likely unpaged because this is a small settings list; no paging clamp needed unless I discover an existing requirement for paging here.
  • GET /api/channel-templates/default (GetDefaultChannelTemplate) returns the configured default template.
  • PUT /api/channel-templates/default/{id:int} (SetDefaultChannelTemplate) validates template exists and records it as default.
  • GET /api/channel-templates/{id:int} (GetChannelTemplateById) returns one template or 404.
  • POST /api/channel-templates (CreateChannelTemplate) creates a user template from a request DTO.
  • PUT /api/channel-templates/{id:int} (UpdateChannelTemplate) updates a user template; system templates should reject mutation unless the existing codebase has a stronger precedent for allowing system row edits.
  • DELETE /api/channel-templates/{id:int} (DeleteChannelTemplate) deletes only user templates; system templates return validation error and deleting the current default should be rejected unless another default is selected first.

DTO shape will be ID/enums/scalars only, friendly to #63 and SPA #89: list rows can show isSystem and isDefault, while create/update request DTOs mirror the template core bundle and leave future Advanced overrides able to reuse the same field names.

## Design approach before coding I read the issue body plus `CLAUDE.md` / `docs/contributing.md` and surveyed the existing channel, schedule, playout, FFmpeg, filler, seeding, and REST API patterns. ### Entity shape / composition decision I will model `ChannelTemplate` as a first-class domain entity that **composes existing entities by reference** instead of duplicating their values: - `FFmpegProfileId` required, referencing the chosen transcode profile. - Optional `WatermarkId`, `FallbackFillerId`, `PreRollFillerId`, `MidRollFillerId`, `PostRollFillerId` referencing the existing watermark/filler preset entities. - The filler IDs will validate against the matching `FillerKind` where applicable. - This keeps template changes aligned with existing profiles/presets and avoids a second copy of FFmpeg/filler configuration that could drift from the source entities. Templates will be **applied at channel creation time by #63**, not live-linked to channels. So deleting or editing a template will not break existing channels created from it. #63 can take `templateId` plus Advanced overrides, resolve the template, and stamp the resulting channel/schedule/playout values into the normal channel creation flow. ### Bundle scope Core bundle fields I plan to persist now: - Identity: `Name`, `Description`, `IsSystem`. - Technical channel defaults: `FFmpegProfileId`, `StreamingMode`, `TranscodeMode`, optional `WatermarkId`, optional `FallbackFillerId`. - Playback/source defaults: `PlayoutSource`, `PlayoutMode`, `IdleBehavior`, `StreamSelectorMode`, `StreamSelector`, audio preference fields. - Subtitle/music-video defaults: `PreferredSubtitleLanguageCode`, `SubtitleMode`, `MusicVideoCreditsMode`, `MusicVideoCreditsTemplate`, `SongVideoMode`. - Schedule/playout defaults for #63: `ShuffleScheduleItems`, `RandomStartPoint`, `FixedStartTimeBehavior`, optional `PreRollFillerId`, `MidRollFillerId`, `PostRollFillerId`. I am intentionally not adding per-item graphics/deco/watermark lists or every schedule-item tail field in this slice. The entity should make #63 and the SPA create flow easy without duplicating the whole schedule editor. If review shows a necessary missing tail field, I will call it out as follow-up rather than expanding the model indefinitely. This shape should also ease #68 later: resume/bookmark behavior can be added as new per-channel/default behavior flags without changing the composition-by-reference decision. ### Built-ins and default selection I will follow `DbInitializer` precedent used for default FFmpeg/profile/config values: - Seed built-in templates during startup after default FFmpeg profile exists. - Built-ins have `IsSystem = true` and cannot be deleted. - Seeding will be idempotent by stable built-in name/key and should not clobber user-created templates. For built-ins, the initializer can create missing rows and leave existing rows alone unless a minimal repair is needed for required references. - Default template selection will be stored with a new `ConfigElementKey` (e.g. `channel_templates.default_template_id`) so the create flow can preselect it without making `IsDefault` mutually exclusive state across rows. - Initial built-ins: `Standard` as default, plus `Music videos` with music-video-friendly defaults. ### REST API surface Under `/api/channel-templates`, using the existing #2a API conventions (`ApiResults`, `NotFoundError`, request DTOs, route `Name = ...`, ProblemDetails metadata, OpenAPI contract tests): - `GET /api/channel-templates` (`GetChannelTemplates`) returns templates, likely unpaged because this is a small settings list; no paging clamp needed unless I discover an existing requirement for paging here. - `GET /api/channel-templates/default` (`GetDefaultChannelTemplate`) returns the configured default template. - `PUT /api/channel-templates/default/{id:int}` (`SetDefaultChannelTemplate`) validates template exists and records it as default. - `GET /api/channel-templates/{id:int}` (`GetChannelTemplateById`) returns one template or 404. - `POST /api/channel-templates` (`CreateChannelTemplate`) creates a user template from a request DTO. - `PUT /api/channel-templates/{id:int}` (`UpdateChannelTemplate`) updates a user template; system templates should reject mutation unless the existing codebase has a stronger precedent for allowing system row edits. - `DELETE /api/channel-templates/{id:int}` (`DeleteChannelTemplate`) deletes only user templates; system templates return validation error and deleting the current default should be rejected unless another default is selected first. DTO shape will be ID/enums/scalars only, friendly to #63 and SPA #89: list rows can show `isSystem` and `isDefault`, while create/update request DTOs mirror the template core bundle and leave future Advanced overrides able to reuse the same field names.
Author
Owner

Done

What was done: Implemented PR #133 (feat/api: channel templates entity + CRUD (#64)) with a first-class ChannelTemplate entity, built-in Standard / Music videos templates, default-template selection, REST CRUD under /api/channel-templates, OpenAPI/typegen updates, and dual-provider EF migrations. Templates compose existing FFmpeg/profile/filler/watermark entities by reference and are designed to be applied at channel creation time by #63, not live-linked to channels.

Root cause: n/a (feature work).

Files changed: Domain/API/Application/Infrastructure/test/OpenAPI/web typegen files for channel templates; migrations 20260706155532_AddChannelTemplates (SQLite) and 20260706155538_AddChannelTemplates (MySQL).

Verification: Local: TZ=UTC dotnet build ErsatzTV.sln passed; TZ=UTC dotnet test ErsatzTV.Tests/ErsatzTV.Tests.csproj passed (417); TZ=UTC dotnet test ErsatzTV.Core.Tests/ErsatzTV.Core.Tests.csproj passed (493 passed / 1 skipped); dotnet build --configuration Release --no-restore passed; SQLite model drift passed; SQLite fresh DB migration apply passed; MySQL model drift passed; cd web && npm ci && npm run generate:api && npm run typecheck passed. CI PR run 259 passed required jobs: Build & test (.NET) and EF migration integrity (SQLite + MySql). Image job skipped for pull_request as expected.

Deferred: MySQL fresh DB apply was not run locally because no MySQL service or Docker binary was available; CI migration integrity passed it. Broader tail fields such as full graphics/deco lists remain out of scope for this slice and can be added later if #63/#89 prove they are needed.

Follow-up issues: #63 composite create-channel endpoint should consume templateId plus Advanced overrides and stamp values into channel/playout/schedule creation. #89 SPA flow can list templates and preselect the default. #68 remains unblocked by this template shape.

Docs updated: n/a beyond PR body/design comment. API surface is captured in regenerated OpenAPI and web/src/api/generated/v1.d.ts.

Leaving #64 open for PR review/merge; PR body contains Closes #64 so merge should close it.

## Done **What was done**: Implemented PR #133 (`feat/api: channel templates entity + CRUD (#64)`) with a first-class `ChannelTemplate` entity, built-in `Standard` / `Music videos` templates, default-template selection, REST CRUD under `/api/channel-templates`, OpenAPI/typegen updates, and dual-provider EF migrations. Templates compose existing FFmpeg/profile/filler/watermark entities by reference and are designed to be applied at channel creation time by #63, not live-linked to channels. **Root cause**: n/a (feature work). **Files changed**: Domain/API/Application/Infrastructure/test/OpenAPI/web typegen files for channel templates; migrations `20260706155532_AddChannelTemplates` (SQLite) and `20260706155538_AddChannelTemplates` (MySQL). **Verification**: Local: `TZ=UTC dotnet build ErsatzTV.sln` passed; `TZ=UTC dotnet test ErsatzTV.Tests/ErsatzTV.Tests.csproj` passed (417); `TZ=UTC dotnet test ErsatzTV.Core.Tests/ErsatzTV.Core.Tests.csproj` passed (493 passed / 1 skipped); `dotnet build --configuration Release --no-restore` passed; SQLite model drift passed; SQLite fresh DB migration apply passed; MySQL model drift passed; `cd web && npm ci && npm run generate:api && npm run typecheck` passed. CI PR run 259 passed required jobs: Build & test (.NET) and EF migration integrity (SQLite + MySql). Image job skipped for pull_request as expected. **Deferred**: MySQL fresh DB apply was not run locally because no MySQL service or Docker binary was available; CI migration integrity passed it. Broader tail fields such as full graphics/deco lists remain out of scope for this slice and can be added later if #63/#89 prove they are needed. **Follow-up issues**: #63 composite create-channel endpoint should consume `templateId` plus Advanced overrides and stamp values into channel/playout/schedule creation. #89 SPA flow can list templates and preselect the default. #68 remains unblocked by this template shape. **Docs updated**: n/a beyond PR body/design comment. API surface is captured in regenerated OpenAPI and `web/src/api/generated/v1.d.ts`. Leaving #64 open for PR review/merge; PR body contains `Closes #64` so merge should close it.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: timothy/ersatztv#64