Channels

Channels turn your movie and TV collection into a TV-style guide of what’s on. Each channel is a schedule built from search queries. Pick a channel in the app and you join wherever the current program is, just like live TV. The guide can be browsed up to a week ahead.

Nothing is actually broadcast. A channel is only a schedule kept by the server, so every device agrees on what’s on. Tuning in plays the existing file from the right position. There’s no transcoding and no per-channel process, and a channel nobody is watching costs nothing.

Channels are available in the Android, Android TV, macOS, iOS, and Linux apps (requires Takeout v0.31.0 or newer). Wear OS doesn’t show channels.

Lineup

Channels are configured in the media config.yaml under Guide. The Lineup is the list of channels, in guide order. Each channel has a name and a Movies query, a Shows query, or both.

Guide:
  Timezone: America/Los_Angeles
  BreakMusic: "+genre:jazz"
  Lineup:
    - {Name: Spooky Season, Layout: Jan, Match: Oct, Movies: "keyword:halloween"}
    - {Name: Horror, Movies: "genre:Horror", BreakMusic: "genre:ambient"}
    - {Name: Sitcoms, Shows: 'series:"The Office" series:"Parks and Recreation"'}
    - {Name: Family Night, Movies: "rating:G rating:PG", Align: 15m}

• Queries use the search syntax. Plain terms are alternatives, so rating:G rating:PG matches either. Prefix + to require a term, as in +genre:Comedy +vote:>7.
• Genres are case-sensitive and use TMDB names: genre:Action and genre:“Science Fiction” match, genre:action doesn’t.
• Show queries match episode fields such as series, title, rating, vote, cast and crew. Series genres aren’t indexed for episodes, so name the series instead.
• Seasonal channels use Layout and Match like movie recommendations, so Spooky Season above only appears in October.
• Names, not numbers. Renaming a channel starts a fresh schedule.

Series play in order, movies don’t repeat on a channel for a while, and the same title isn’t on two channels at once. Configuration changes affect programs that aren’t scheduled yet, so they show up over the next week.

Guide Settings

A Lineup entry can override Align, MinBreak, MinContent, and BreakMusic for that channel. Use a lower MinContent for a channel that loops one short series.

Music Breaks

Programs start on Align marks, so there are short gaps between them. Gaps are filled with music from BreakMusic (the channel’s, else the guide’s, else any track). Break tracks need a MusicBrainz recording ID and a scanned duration. Longer breaks are shown in the guide as Music.

Specials

A special is an occasional themed block that viewers stumble onto, like a film collection marathon or Tom Cruise Night. The scheduler picks an evening about every Every and rotates through the specials so each comes round in turn. The same special isn’t run on two channels in the same week.

Guide:
  Lineup:
    - Name: Action
      Movies: "genre:Action"
      Specials:
        Every: 720h
        At: "20:00"
        MaxLength: 12h
        Collections: true
        MinFilms: 3
        Skip: ["Twilight Collection"]
        Themes:
          - Name: Tom Cruise Night
            Movies: 'cast:"Tom Cruise"'
          - Name: Arnold Marathon
            Movies: 'cast:"Arnold Schwarzenegger"'
            Order: date

A collection special plays every film you own from that collection in release order, even ones the channel’s query didn’t match.

Features

A feature is a regular slot viewers learn to expect, like Friday night is new movies. The slot is reserved in the guide with the feature’s name, and filled about a day before it airs with titles the feature hasn’t shown yet, so a movie added on Monday makes that Friday. With nothing new, the slot becomes regular programming.

Guide:
  Lineup:
    - Name: Good Movies
      Movies: "vote:>7"
      Features:
        - Name: New on Friday
          Layout: Mon
          Match: Fri
          At: "20:00"
          Length: 4h
          Source: added
          Description: Movies new to the library this week
        - Name: Sunday Matinee
          Layout: Mon
          Match: Sun
          At: "14:00"
          Length: 3h
          Movies: "genre:Family"
        - Name: First of the Month
          Layout: "2"
          Match: "1"
          At: "20:00"
          Length: 4h
          Source: released

A feature uses its own source or query, not the channel’s. A feature wins over a special at the same time, and when features overlap the first one listed wins. A channel can have both specials and features.

Durations

Schedules use the real running time of each file, read from the file headers (mkv, mp4/m4a, flac, ogg, and mp3). Hourly jobs scan durations in batches; see DurationSyncInterval and DurationSyncLimit in the configuration. A title without a scanned duration uses its TMDB runtime plus 2 minutes until it’s scanned.

To scan durations or extend the schedule right away, run the jobs:

$ takeout job --name durations
$ takeout job --name guide

API

GET /api/guide returns the channels and what’s on each one, from now to 3 hours ahead by default. Use start and end (RFC3339) to ask for another range, up to the horizon. GET /api/index includes HasGuide when channels are configured.