wittytuner

package module
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: Apache-2.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
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.

Recording and the guide stay with the server.

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. That needs WittyMediaServer 0.6.0-alpha or later, and it works with nothing older. The range this version fits is in module.json: 0.6.0-alpha through 0.6.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 three permissions: network, running programs, and devices. 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.

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. 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

Apache-2.0: see LICENSE and NOTICE. If you redistribute it or build on it, 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.3.0 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 Apache-2.0: 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 ManifestJSON []byte

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

Functions

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"`
}

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 HelperCall added in v0.2.0

type HelperCall struct {
	Driver  string            `json:"driver,omitempty"`
	Name    string            `json:"name,omitempty"`
	Options map[string]string `json:"options,omitempty"`
	Channel *Channel          `json:"channel,omitempty"` // "open" and "recheck"
	Source  string            `json:"source,omitempty"`  // "scan": ScanOptions.Source
	// What it can't find out for itself.
	FFmpeg        string `json:"ffmpeg,omitempty"`
	AllowCommands bool   `json:"allowCommands,omitempty"`
}

HelperCall is what a helper is asked: which tuner, since it keeps nothing, and what for.

type HelperDoc added in v0.2.0

type HelperDoc struct {
	Progress     *Progress   `json:"progress,omitempty"`
	Channels     []Channel   `json:"channels,omitempty"`
	Info         *Info       `json:"info,omitempty"`
	GuideHeaders http.Header `json:"guideHeaders,omitempty"`
	Found        []Found     `json:"found,omitempty"`
	Drivers      []Driver    `json:"drivers,omitempty"`
	Why          string      `json:"why,omitempty"`  // "recheck": why it's encrypted now
	Next         int64       `json:"next,omitempty"` // "recheck": seconds until it's worth asking again
	Error        string      `json:"error,omitempty"`
	Code         string      `json:"code,omitempty"`
	Done         bool        `json:"done,omitempty"`
}

HelperDoc is one document of an answer. Progress may come any number of times; any other document ends the answer.

type HelperOpen added in v0.2.0

type HelperOpen struct {
	Input []string `json:"input,omitempty"`
	// Verified: it was inspected on opening and found clear. Recheck: it can change while it
	// plays, so it's worth asking again.
	Verified bool `json:"verified,omitempty"`
	Recheck  bool `json:"recheck,omitempty"`
}

HelperOpen is the answer to "open" for a stream FFmpeg should open by itself. The server holds what it asks for to its own rules before FFmpeg sees any of it.

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
cmd
wittytuner-module command
Command wittytuner-module is WittyTuner as a helper process: the only way a server reaches it.
Command wittytuner-module is WittyTuner as a helper process: the only way a server reaches 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 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