Repository navigation
Description
Origin
Product-owner requirement on 2026-09-14 while discussing multiple M3U playlist aggregation.
ChannelForge should support importing multiple M3U playlists and aggregating them into one canonical accepted lineup and one coherent M3U/XMLTV output set. The user also wants to choose their own channel numbers and be asked how to handle duplicate/same-channel sources.
Follow-up product-owner requirement: the multi-lineup and guide-merge behavior must be documented explicitly. It is not enough to imply aggregation through one M3U output; ChannelForge must define how multiple playlists and one or more XMLTV/guide sources are reconciled into one coherent accepted output.
Requirement
ChannelForge must support user-controlled channel numbering and explicit duplicate-resolution decisions when aggregating multiple M3U playlist sources.
For example:
Canonical channel: ESPN
Sources:
- Provider A stream
- Provider B stream
Guide:
- XMLTV channel id: ESPN.us / provider-specific equivalent
Policy:
- prefer Provider A
- fail over to Provider B
ChannelForge must not silently flatten that into duplicate ESPN rows or silently choose a provider without evidence and user policy.
Product behavior
When multiple playlist entries appear to represent the same canonical channel, ChannelForge should present a beginner-readable decision such as:
ChannelForge found ESPN in more than one playlist.
What should happen?
1. Keep both streams and use Provider B as failover if Provider A fails.
2. Prefer Provider B and use Provider A as failover.
3. Keep only Provider A.
4. Keep only Provider B.
5. Keep both as separate channels.
6. Ask me later / mark review needed.
The default recommendation should be evidence-based and safe, but the user must remain in control when the decision materially changes the lineup.
Multi-lineup and guide merge documentation requirement
ChannelForge must document the end-to-end aggregation model for multiple M3U playlists and one or more XMLTV/guide sources.
The documentation must explain, in beginner-readable terms and accurate IPTV/XMLTV terminology:
- what an M3U playlist contributes: stream URLs, channel display names, groups, provider
tvg-idhints, logos, provider channel numbers, and source provenance; - what an XMLTV guide contributes: channel identities, programme schedules, titles, descriptions, timings, categories, and guide provenance;
- what a canonical channel is: ChannelForge's accepted representation of a real channel after comparing one or more provider rows and guide identities;
- what a source variant is: an alternate stream/source observation for the same canonical channel;
- what a guide binding is: the selected XMLTV channel identity/programme source for one canonical channel;
- why multiple playlist entries do not automatically mean multiple visible channels;
- why multiple guide entries do not automatically mean duplicate programme rows;
- how ChannelForge distinguishes identical channels, regional variants, alternate feeds, event channels, and ambiguous candidates.
Multi-lineup merge behavior
When importing multiple M3U playlists, ChannelForge must:
- keep each playlist as a named source with preserved provenance;
- normalize and compare playlist entries before proposing a canonical lineup;
- detect candidate duplicates across playlists;
- preserve provider names, source IDs, provider channel numbers, group titles, stream fingerprints,
tvg-idhints, logos, and first/last observed metadata; - propose safe default duplicate policies only when evidence is strong;
- ask the user when the choice materially changes the accepted lineup;
- record the accepted duplicate-resolution policy in the decision manifest once acceptance is implemented;
- preserve accepted user choices across reruns unless the user changes them or a safe migration is explicitly accepted.
Multi-guide / XMLTV merge behavior
When one or more XMLTV/guide sources are available, ChannelForge must:
- preserve every guide source as a named source with provenance and freshness;
- compare guide channel identities against canonical channels;
- bind each canonical channel to the intended XMLTV channel identity where evidence is exact or explicitly accepted;
- surface conflicts when multiple guide sources disagree on channel identity, programme timing, regional variant, or metadata;
- preserve guide-source priority and field-level provenance where one source is selected over another;
- avoid duplicate programme rows for one canonical channel unless the user intentionally configures that output behavior;
- distinguish guide-source mirrors from independent corroborating sources;
- respect freshness, stale-source, unavailable-source, and last-known-good boundaries;
- produce a deterministic XMLTV output from the accepted canonical lineup and accepted guide-binding policy.
Cross-product output model
The intended accepted output is:
Multiple M3U playlist sources
-> source observations and stream variants
-> one canonical accepted lineup
-> user-selected channel numbers and duplicate policy
-> accepted guide bindings from one or more XMLTV sources
-> one deterministic output M3U
-> one deterministic output XMLTV guide
The output reports must show:
- each accepted canonical channel;
- selected channel number;
- selected display name;
- contributing playlist sources;
- selected primary stream and failover/alternate streams;
- selected guide/XMLTV binding;
- guide-source provenance and freshness;
- unresolved duplicate or guide conflicts;
- whether the channel is safe to accept, review-needed, or blocked.
Custom channel numbers
Users must be able to assign their own channel numbers for the accepted lineup.
Requirements:
- A user-selected channel number belongs to the canonical accepted lineup, not blindly to one provider row.
- Provider-supplied channel numbers remain preserved as source evidence/provenance.
- ChannelForge may recommend numbers from provider data or guide data, but user-selected numbering wins after explicit acceptance.
- Duplicate custom numbers require a clear conflict/review state before acceptance.
- Number changes must be deterministic and visible in the candidate review.
- Re-running a build must preserve accepted user-selected numbers unless the user changes them or a safe migration is explicitly accepted.
Duplicate-resolution policy
For duplicate or same-channel candidates across playlists, ChannelForge must support at least:
Failover: one canonical channel with ordered stream sources.PreferSource: one canonical channel with a primary source and retained alternate(s).KeepOnly: one canonical channel using only the selected source.KeepSeparate: multiple canonical channels when the user intentionally wants separate rows.ReviewNeeded: no automatic acceptance because identity or policy is ambiguous.
The policy must be recorded with provenance and included in the accepted generation/decision manifest when acceptance is implemented.
Guide/XMLTV behavior
- A canonical channel should bind to one intended XMLTV guide identity unless the user explicitly configures an alternate output behavior.
- Multiple streams for the same canonical channel should not create duplicate XMLTV programme rows by default.
- If provider entries disagree on
tvg-id, ChannelForge must show the conflict and request review or apply an already accepted policy. - If XMLTV sources disagree, ChannelForge must show the conflict, preserve provenance, and use only an accepted source/field policy.
- Custom channel numbers must be reflected in M3U output ordering/metadata where the selected output profile supports it.
- XMLTV
channelidentity must remain stable and not be rewritten merely because the user changes display order or channel number, unless the output profile explicitly requires a presentation-only transform.
Safety and UX requirements
- Do not silently delete duplicates.
- Do not silently merge duplicates when evidence is weak.
- Do not silently publish ambiguous guide mappings.
- Do not silently pick one XMLTV guide source over another when the conflict materially changes the guide.
- Explain duplicate decisions in plain language.
- Explain guide-binding conflicts in plain language.
- Preserve all source/provider/guide provenance.
- Keep advanced priority/failover rules out of the beginner path unless needed.
- Beginner default should be: recommend the safest option, ask only when the decision materially changes what appears in the final lineup or guide.
Related work
- EPG Acquisition and Merge — multi-lineup identity, validation, provenance, and deterministic XMLTV #40 — EPG Acquisition and Merge / multi-lineup identity and deterministic XMLTV
- Autonomous Operations — scheduled refresh, multi-guide learning, source drift detection, and zero-touch maintenance #35 — autonomous operations, refresh, source drift, and zero-touch maintenance
- High-Performance Data Store — fast identity, guide, event, provenance, and incremental-build indexing #36 — indexed store for source variants, provenance, and stable accepted mappings
- Product-wide intent-fit code audit and standing implementation gate #141 — product-wide intent-fit implementation gate
- UI architecture requirement: web-first local UI, Docker or Windows server install #150 — web-first UI architecture; this workflow must be browser UI compatible
Acceptance criteria
- Multiple M3U playlists can contribute to one canonical accepted lineup.
- Multiple XMLTV/guide sources can contribute to one coherent guide-binding plan and one deterministic XMLTV output.
- Duplicate/same-channel candidates surface an explicit resolution choice.
- User-selected channel numbers are supported and persist across reruns.
- Provider channel numbers are preserved as source evidence, not overwritten.
- Failover/preferred-source/keep-only/keep-separate/review-needed policies are represented deterministically.
- Ambiguous duplicates block acceptance until resolved or safely marked review-needed.
- Guide/XMLTV output avoids duplicate programme rows for one canonical channel unless explicitly configured.
- XMLTV guide-source conflicts are shown with provenance and block acceptance unless resolved by accepted policy.
- Output reports show selected channel number, contributing sources, chosen duplicate policy, guide binding, guide-source provenance/freshness, and any unresolved conflicts.
- Beginner documentation explains the multiple-M3U/multiple-guide merge model without requiring the user to understand internal data structures.
- Tests cover duplicate ESPN across two providers, custom channel numbering, number collision, conflicting
tvg-id, conflicting XMLTV guide identity, conflicting programme metadata, failover, keep-only, keep-separate, and stable rerun preservation.
Definition of done
A user can import multiple M3U playlists, choose their preferred channel numbers, resolve duplicates using clear beginner-readable choices, merge one or more XMLTV/guide sources with explicit provenance and conflict handling, and produce one deterministic accepted lineup and guide output without losing provider provenance or silently publishing ambiguous mappings.
Activity
Jumpstile commentedon Oct 23, 2026
Duplicate-row identity and category namespace evidence — 2026-10-23
Observed 12:56 UTC. First-party m3u-editor development 2eab0eae, Oct23 00:44 UTC, AFTER stable v0.13.6. Source/fixtures inspected, not executed. NEW after exact-SHA search and 14-day canonical reconciliation; #153 is the specific duplicate-resolution owner.
Why/recommendation: Adopt regression cases / Study implementation for reordered duplicate names with distinct, missing, repeated and zero IDs; preserve source-scoped prior/new identity and require review for ambiguous continuity. Test colliding numeric category IDs from different namespaces and temporarily out-of-scope selections. Do not elevate tvg-id text to global identity or copy ordinal fallback into silent duplicate acceptance.
Classification Compatibility impact / Study; medium priority, high identity-safety fixture value. Scope #153; related #27/#31/#175. Confidence high inspected source, runtime and migration behavior unverified. No demonstrated ChannelForge defect, release blocker, automatic merge, installation or accepted-state change. Existing labels/milestone retained.
Document how multiple playlists and guides become one lineup (#153) (#…
Jumpstile commentedon Nov 17, 2026
Progress, 11/17/2026: PR #271 merged. It adds docs/architecture/MULTI_LINEUP_AGGREGATION.md, a beginner-readable note on how multiple playlists and guides become one lineup, based on what main does today and naming the code each part lives in.
Still NOT built (found by reading the code, listed in the note): user-chosen channel numbers (PreferredNumber exists on Channel but nothing reads it; numbers come only from numbering blocks by group), the six-choice duplicate decision (only four choices exist: KeepWithoutGuide, OwnPlaceholder, BindTrueMatch, ShareOnPurpose, and only via Build-My-Lineup), provider failover, regional-variant detection, and merging programmes across different guides. Keeping #153 open for those.
Not verified: the ESPN worked example was read from code order, not run.
https://claude.ai/code/session_01NzHAcjThVoUGWWfXrYWsNh