wittytuner

package module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: AGPL-3.0 Imports: 36 Imported by: 0

README

WittyTuner

Brings live TV into WittyMediaServer: network tuners, IPTV playlists, capture cards and guide data. You need it if you want live TV or recording.

The programme guide, with a film playing in the preview

The guide, here with channels made from a library, playing Caminandes: Llamigos, Pablo Vazquez, Blender Foundation, CC BY 3.0. From a test server. The server's credits list names everything shown.

The channels and tuners page in Settings

Settings, Channels & tuners, on a server with no tuner attached.

The recordings page

Recordings, on a server with none yet.

What it does

A driver lists channels and opens one, as raw MPEG-TS or as options for FFmpeg.

Driver Reaches Systems How far it's been tested
iptv M3U and M3U8 playlists All Automated tests, and FFmpeg against local streams
xtream IPTV provider accounts on Xtream Codes-style panels: channels, groups, guide and catch-up All Against a stand-in panel, not a real provider
stream One HTTP, HLS, RTSP, RTP, UDP, RTMP or SRT address All Automated tests, and FFmpeg against local streams
network HDHomeRun-style network tuner boxes All Against a stand-in device, not real hardware
backend TV servers over open protocols: an HTTP API with M3U and XMLTV, or SVDRP All Against stand-in servers, not a real one
satip SAT>IP servers All Protocol tests, not real hardware
dvb Linux DVB-T/T2, DVB-C, DVB-S/S2, ATSC, ClearQAM, ISDB-T, with band scans and channels.conf import Linux Parsers and band plans, not real hardware. No DiSEqC yet
v4l2 Analogue tuner and capture cards Linux Argument tests, not real hardware
dshow Capture cards through DirectShow Windows Listing tested, not with a card
avfoundation Capture devices macOS Parser tests only
command Your own program writing MPEG-TS. Off unless the server is started with WMS_TUNER_COMMANDS=1 All Automated tests with a test program
bda Digital tuners through BDA Windows Not built. Listed so the gap is visible

It also reads guide data from broadcasts (DVB EIT and ATSC PSIP) and from XMLTV files.

Encrypted and copy-protected channels are refused, with a clear message, and nothing is decrypted. It checks lineups, stream tables, the packets themselves as they play, DRM lines in playlists, and any key line in an HLS playlist. The check applies to every driver, and there's no way to change it. The server also watches every stream itself, whatever a module says.

No channel lists or stream addresses come with it. Band scans only say where a channel could be.

Since 0.4.0 (module API 5) WittyTuner owns its whole part of live TV: the tuners, their channels and the guide sources are in its own database, and Settings → Live TV & tuners, the first-run step and the encrypted-channels page are its own screens. The guide, recordings, favourites and sets stay with the server, which opens every channel through WittyTuner and watches every stream itself.

How to use it is in Help inside WittyMediaServer: see Channels and live TV.

How to get it

An admin adds it from the module store inside WittyMediaServer: Settings → Modules, then Browse the store, then Add beside WittyTuner. This version needs a WittyMediaServer of module API 5 (0.8.0-alpha or later). The range this version fits is in module.json: 0.8.0-alpha through 0.8.x.

What it needs

  • FFmpeg, which comes with the server.
  • A tuner or an IPTV playlist.
  • WittyModule, which is how a server talks to it, built in.

It asks the server for four permissions: network, running programs, devices, and a data folder of its own for its database. It's written in Go with no cgo.

Platforms

A program is built for each system below, and the server uses the right one.

System Where it stands
Linux (x64, arm64, 32-bit ARM, x86) Its tests pass on x64. No real tuner or capture card has been tried on any system. The other CPUs are only built
Windows (x64, arm64) Built. This version hasn't been run on Windows since it became its own program
macOS (Intel, Apple silicon) Built by the release tool. It has not been run on a real Mac
FreeBSD (amd64, arm64) Cross-compiled only. It has not been run

On macOS and FreeBSD the server has no sandbox for a module's helper: it gets a small environment and a soft memory limit, and nothing more.

In the apps

WittyTuner is a service (module API 5: WittyMediaServer docs/MODULES-API5.md):

  • Its routes (integration.json, package api) are mounted by the server at /api/modules/wittytuner/…: the tuners, their channels and checks, duplicate channels, the guide sources, and the first-run step. Every one but the encrypted-channels page (/encrypted-help, for anyone signed in) is an administrator's.
  • Its own routes for the server (/tv/…, never a person's): every channel for the guide, opening one within its tuner's limit (MPEG-TS handed over, or an address FFmpeg opens under the server's own rules), letting it go, looking at a playlist again, and what the server's guard saw. The server never takes WittyTuner's word that a channel is clear.
  • Its data is a SQLite database in its own folder (package store): tuners, channels and guide sources. A guide source is fetched here and handed to the server (the host API's POST /tv/guide/{source}), which keeps the guide.
  • sdui.json (written from package ui; go test ./ui -update-sdui) has its pages for every app, the Apple TV and Android TV apps among them: the tuners with what's on this network to add, one tuner's channels, and the first-run step. Their sources are answered by the service, and every row runs one of its own commands.
  • Its web part (web/, built with WittyModule's kit/web/build-bundle.mjs; npm test checks it) is Settings → Live TV & tuners, the first-run step and the encrypted-channels page in the browser.

Building and testing

You need Go 1.26 or newer. In a worktree, first run the copy of dev-modules.mjs kept above the repositories (node D:/projects/dev-modules.mjs on the development machine). It writes a go.work that git ignores, so the checkout builds against the repositories beside it. Never run go work use.

go vet ./...
go test ./... -count=1
go run github.com/wittywilla/wittymodule/cmd/wittymodule check .

The last one checks the manifest, integration.json and sdui.json. The web part is built with npm ci && npm run build:bundle (WittyModule beside this checkout, or WITTYMODULE). On the same tool, pack -targets linux/amd64 -out release . builds a release for one system. CI also builds for every system.

To use it as a library, wittytuner.New(driver, config, env) gives a source with Channels and Open. wittytuner.Drivers(env) describes every driver and its settings, and wittytuner.Discover(ctx, env) looks for tuners. The custom command driver stays off unless the host sets Env.AllowCommands.

Licence

GNU Affero General Public License v3.0 (or later): see LICENSE and NOTICE. If you redistribute it or build on it, please keep the NOTICE attribution. Each release archive carries a THIRD-PARTY-NOTICES.txt for what its programs link.

WittyTuner is an independent open-source project. It isn't associated with, sponsored by or endorsed by any tuner maker, broadcaster, IPTV provider or guide service. No channel lists or stream addresses come with it. Encrypted channels are refused and nothing is decrypted. What a tuner or a provider offers belongs to them, and you're responsible for having the rights to what you receive and record. Any third-party names here only describe what it works with, and belong to their owners. It's provided “as is”, with no warranty; see LICENSE. Local law applies to how you use it. This isn't legal advice.

Releasing

A version tag builds a program for every platform, signs the checksum list, and publishes a release that servers can install.

Versions move in small steps as work lands. go run github.com/wittywilla/wittymodule/cmd/wittymodule@v0.5.4 bump . raises it everywhere it is written (add -part minor for a bigger step). A bump isn't a release: nothing is tagged or published until you tag it. CI fails when code changed since the last tag and the version didn't, because tags never move.

To release:

  1. Check that version in module.json is the one to publish, with the bump committed.
  2. Tag that commit and push the tag: git tag vX.Y.Z, then git push origin vX.Y.Z. A tag with a suffix, such as v1.2.0-beta, is published as a prerelease.
  3. Watch the Actions tab. The signing step uses the WMS_SIGNING_KEY secret of the release environment, and nothing is published without it.

To take a version back, run the withdraw workflow from the Actions tab. It adds the version to a signed list on the release tagged withdrawals, which servers read.

Licensed under AGPL-3.0-or-later: see LICENSE and NOTICE.

Documentation

Overview

Package wittytuner is a common way to reach TV tuners and IPTV: network tuners, M3U playlists and single streams, Linux DVB, V4L2 capture, Windows and macOS capture devices, SAT>IP, external backends over open protocols and a custom command.

A driver lists channels and opens one as either raw MPEG-TS or FFmpeg input options. Encrypted and copy-protected channels are detected and refused: nothing here decrypts or bypasses anything.

Index

Constants

View Source
const (
	EncryptedLabel = "Encrypted: can't be played here"

	// EncryptedExplain is the same in one line, for lists.
	EncryptedExplain = encryptedBecause + ". " + encryptedPolicy
)

What every client shows for an encrypted channel, so that nobody takes it for a fault in their setup.

View Source
const ScrambledReason = "the signal itself is scrambled"

ScrambledReason says why a stream stopped by the guard was refused.

Variables

View Source
var ErrBusy = errors.New("all of this device's tuners are in use")

ErrBusy: every tuner of the source is in use.

View Source
var IntegrationJSON []byte

IntegrationJSON is what this module adds to the server (module API 5: docs/MODULES-API5.md in WittyMediaServer, "integration.json").

View Source
var ManifestJSON []byte

ManifestJSON is this module's manifest (docs/MODULES.md, "The manifest").

Functions

func ArchiveURL added in v0.3.0

func ArchiveURL(ch Channel, now time.Time) (string, error)

ArchiveURL is the address of what a channel showed from ArchiveStart to ArchiveEnd, built the way its source says. It refuses a channel with no catch-up, and a time the source no longer keeps or hasn't shown yet.

func HelperLog added in v0.4.0

func HelperLog() *slog.Logger

HelperLog is the log of WittyTuner's service: stderr, which the server reads line by line, in the Live TV area and at the level the server asks for.

func IsEncrypted

func IsEncrypted(err error) bool

IsEncrypted reports whether err means a channel was refused for encryption.

func LocalPlaylist added in v0.2.0

func LocalPlaylist(place string) bool

LocalPlaylist says a playlist's place is on the owner's own network: a file, an address at home or on a private network, or a name only a local network can resolve. A name anyone can register can point anywhere, so it doesn't count, whatever it resolves to now. The owner typed this address, so a playlist from elsewhere can't choose it.

func ParseAVFDevices

func ParseAVFDevices(out string) (video, audio []string)

ParseAVFDevices reads the output of ffmpeg -f avfoundation -list_devices true.

func ParseDShowDevices

func ParseDShowDevices(out string) (video, audio []string)

ParseDShowDevices reads the output of ffmpeg -list_devices true -f dshow.

func RefusalMessage

func RefusalMessage(name string, err error) error

RefusalMessage turns a stream that a guard stopped into words for a person.

func SecretFields

func SecretFields(driver string) []string

SecretFields lists settings a driver treats as passwords, never sent back to a browser.

func SplitCommand

func SplitCommand(s string) ([]string, error)

SplitCommand splits a line into arguments, with single and double quotes and nothing else special.

Types

type Channel

type Channel struct {
	ID       string `json:"id"` // stable within the source
	Number   string `json:"number"`
	Name     string `json:"name"`
	Group    string `json:"group,omitempty"`
	CallSign string `json:"callsign,omitempty"`
	Locator  string `json:"locator,omitempty"` // how the driver finds it again
	EPGID    string `json:"epgId,omitempty"`   // XMLTV channel id
	HD       bool   `json:"hd,omitempty"`
	Radio    bool   `json:"radio,omitempty"`
	Program  int    `json:"program,omitempty"` // MPEG program number
	// Encrypted is why this channel cannot be tuned ("" = it can).
	Encrypted string `json:"encrypted,omitempty"`
	// Checked: the source says for itself whether this channel is protected,
	// so no Encrypted reason means it is clear. Otherwise nobody knows until
	// the channel is first tuned.
	Checked bool `json:"checked,omitempty"`
	// ATSC3: an ATSC 3.0 (NextGen TV) broadcast.
	ATSC3      bool   `json:"atsc3,omitempty"`
	VideoCodec string `json:"videoCodec,omitempty"` // as the source names it: HEVC, MPEG2…
	AudioCodec string `json:"audioCodec,omitempty"` // AC4, AC3…
	// NoRecord is why the device says this channel may not be recorded.
	NoRecord string `json:"noRecord,omitempty"`
	// Catch-up: the source keeps what it showed for CatchupDays, and Catchup says how
	// to ask for it (default, append, shift, flussonic or xc). CatchupSource is the
	// source's own template for the address, which can hold a login as Locator can.
	CatchupDays   int    `json:"catchupDays,omitempty"`
	Catchup       string `json:"catchup,omitempty"`
	CatchupSource string `json:"catchupSource,omitempty"`
	// ArchiveStart and ArchiveEnd (Unix seconds) are set by the host, and only to ask
	// Open for what the channel showed then instead of what it shows now.
	ArchiveStart int64 `json:"archiveStart,omitempty"`
	ArchiveEnd   int64 `json:"archiveEnd,omitempty"`
}

Channel is one channel a source offers.

func ParseChannelsConf

func ParseChannelsConf(system, text string) []Channel

ParseChannelsConf reads a file from dvbv5-scan (the [name] / key = value format) or the older colon-separated zap format. Encrypted entries are kept, marked, so people can see why they do not play.

type Config

type Config struct {
	Name    string
	Options map[string]string
}

Config is one tuner's settings.

type Driver

type Driver struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	// Status is how well this has been tested: "tested", "mock" (against mock
	// servers, no real device) or "untested".
	Status string `json:"status"`
	// Platforms it can run on; empty = all.
	Platforms []string `json:"platforms,omitempty"`
	Fields    []Field  `json:"fields"`
	Scans     bool     `json:"scans"` // Scan does more than list what is known
	// Planned drivers are listed so people can see they are known about.
	Planned bool `json:"planned,omitempty"`
	// Available is worked out for this machine.
	Available bool   `json:"available"`
	Note      string `json:"note,omitempty"`
	// contains filtered or unexported fields
}

Driver describes one kind of tuner.

func Drivers

func Drivers(env Env) []Driver

Drivers lists every kind of tuner, marked for what works on this machine.

type EncryptedError

type EncryptedError struct {
	Channel string
	Why     string
}

EncryptedError says a channel was refused because it is encrypted or copy protected. It is never decrypted.

func (*EncryptedError) Error

func (e *EncryptedError) Error() string

type Env

type Env struct {
	HTTP *http.Client // for short requests
	// Stream is for long-lived streams: it must have no overall timeout.
	Stream *http.Client
	FFmpeg string
	// Command prepares a process (the host hides console windows and so on).
	Command func(ctx context.Context, name string, args ...string) *exec.Cmd

	// AllowCommands: the owner has allowed the custom command driver.
	AllowCommands bool
	// Log is where drivers say what went wrong; nil says nothing. Records are
	// written with the context the host passed in, so its session comes along.
	Log *slog.Logger
	// contains filtered or unexported fields
}

Env is what a driver gets from its host.

func HelperEnv added in v0.2.0

func HelperEnv(home bool) Env

HelperEnv is the Env for a helper. home says the stream was named by the owner or a playlist on the home network, so it may lead there; anything else stays on the internet.

func HelperEnvFor added in v0.2.0

func HelperEnvFor(driver string, options map[string]string) Env

HelperEnvFor is the Env for a call about this tuner.

type Field

type Field struct {
	Key      string   `json:"key"`
	Label    string   `json:"label"`
	Kind     string   `json:"kind"` // text | url | path | password | select | number | textarea | toggle
	Help     string   `json:"help,omitempty"`
	Default  string   `json:"default,omitempty"`
	Required bool     `json:"required,omitempty"`
	Options  []string `json:"options,omitempty"`
}

Field describes one setting of a driver; forms are drawn from these.

type Found

type Found struct {
	Driver  string            `json:"driver"`
	Name    string            `json:"name"`
	Detail  string            `json:"detail,omitempty"`
	Options map[string]string `json:"options"`
}

Found is a tuner discovered on this network or machine, ready to add.

func Discover

func Discover(ctx context.Context, env Env) []Found

Discover looks for tuners: on the local network and among this machine's devices. It takes a couple of seconds.

func DiscoverHere added in v0.2.0

func DiscoverHere(ctx context.Context, env Env) []Found

DiscoverHere is the part of Discover that looks at this machine's own devices.

func DiscoverNetwork added in v0.2.0

func DiscoverNetwork(ctx context.Context, env Env) []Found

DiscoverNetwork is the part of Discover that only needs a network.

type Info

type Info struct {
	Driver     string
	Name       string
	MaxStreams int    // how many channels it can stream at once; 0 = no known limit
	Detail     string // model, address: shown in Settings
	GuideURL   string // an XMLTV address the source offers
}

Info describes a configured source.

type M3U

type M3U struct {
	GuideURL string
	Entries  []M3UEntry
	Skipped  int
}

M3U is a parsed playlist.

func ParseM3U

func ParseM3U(r io.Reader) (*M3U, error)

ParseM3U reads an extended M3U playlist. Comments it does not understand are skipped, so one odd line does not lose a channel list.

type M3UEntry

type M3UEntry struct {
	Channel
	URL string
}

M3UEntry is one channel of a playlist.

type Progress

type Progress struct {
	Percent int    `json:"percent"`
	Found   int    `json:"found"`
	Message string `json:"message,omitempty"`
}

Progress is how far a scan has got.

type ScanOptions

type ScanOptions struct {
	Source string // Antenna | Cable: for tuners that ask
}

ScanOptions tune a scan.

type Source

type Source interface {
	Info() Info
	// Channels is what the source knows now, without tuning anything.
	Channels(ctx context.Context) ([]Channel, error)
	// Scan looks for channels. It may take minutes, and is cancelled by ctx.
	Scan(ctx context.Context, o ScanOptions, progress func(Progress)) ([]Channel, error)
	// Open starts a channel. ErrBusy when no tuner is free, *EncryptedError
	// when the channel is encrypted.
	Open(ctx context.Context, ch Channel) (*Stream, error)
	Close() error
}

Source is one configured tuner.

func New

func New(driver string, cfg Config, env Env) (Source, error)

New makes a source from its settings. Required settings are checked here.

type Stream

type Stream struct {
	Reader io.ReadCloser
	Input  []string
	// Guard watches a Reader for scrambling and collects guide data. Set
	// OnEvent on it before reading to receive that data.
	Guard *mpegts.Guard
	// Verified: an Input stream was inspected on opening and found clear.
	Verified bool
	// Recheck looks again at an Input stream that can change while it plays. It says
	// why the stream is now encrypted, or "", and how long until it's worth asking again.
	// An error is a failure to find out, which says nothing about the stream.
	Recheck func(ctx context.Context) (why string, next time.Duration, err error)
}

Stream is an open channel: Reader for raw MPEG-TS, else Input for FFmpeg.

func (*Stream) Close

func (s *Stream) Close() error

Close releases what the stream holds.

type Tuning

type Tuning struct {
	System     string
	Frequency  int64
	Bandwidth  int // Hz
	SymbolRate int
	Pol        string
	Modulation string
}

Tuning is what a channel needs to be found again. Frequency is in Hz; for satellite, kHz as broadcasters publish it.

func ParseLocator

func ParseLocator(s string) (Tuning, int, error)

ParseLocator reads a kept tuning back.

func (Tuning) Locator

func (t Tuning) Locator(program int) string

Locator is how a tuning is kept with a channel.

Directories

Path Synopsis
Package api is WittyTuner's own HTTP API (module API 5): the routes WittyMediaServer passes to it at /api/modules/wittytuner/...
Package api is WittyTuner's own HTTP API (module API 5): the routes WittyMediaServer passes to it at /api/modules/wittytuner/...
cmd
wittytuner-module command
Command wittytuner-module is WittyTuner as a service (module API 5), which the server starts by itself: its own routes (Settings, Live TV & tuners, the first-run step), its SDUI pages' sources, the guide sources it fetches on a schedule, and the channels the server's live TV, recordings and catch-up open through it.
Command wittytuner-module is WittyTuner as a service (module API 5), which the server starts by itself: its own routes (Settings, Live TV & tuners, the first-run step), its SDUI pages' sources, the guide sources it fetches on a schedule, and the channels the server's live TV, recordings and catch-up open through it.
Package mpegts reads the parts of an MPEG transport stream a TV tuner needs: the scrambling bits, what the stream says it carries (PAT, PMT, SDT, ATSC VCT) and the programme guide inside it (DVB EIT, ATSC PSIP).
Package mpegts reads the parts of an MPEG transport stream a TV tuner needs: the scrambling bits, what the stream says it carries (PAT, PMT, SDT, ATSC VCT) and the programme guide inside it (DVB EIT, ATSC PSIP).
Package store is WittyTuner's own database (module API 5): a SQLite file in the module's own folder (WITTYMODULE_DATA), with migrations WittyTuner owns.
Package store is WittyTuner's own database (module API 5): a SQLite file in the module's own folder (WITTYMODULE_DATA), with migrations WittyTuner owns.
Package ui is WittyTuner's server-driven UI (module API 5; WittyMediaServer docs/SDUI-MODULES.md): the tuner pages every app draws, the Apple TV and Android TV apps among them, which have no web view for the module's web part.
Package ui is WittyTuner's server-driven UI (module API 5; WittyMediaServer docs/SDUI-MODULES.md): the tuner pages every app draws, the Apple TV and Android TV apps among them, which have no web view for the module's web part.
Package xmltv reads XMLTV guide files as they stream by, so a very large guide needs very little memory.
Package xmltv reads XMLTV guide files as they stream by, so a very large guide needs very little memory.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL