wittytuner

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: Apache-2.0 Imports: 32 Imported by: 0

README

WittyTuner

One way to reach every kind of TV tuner, from Go.
Network tuners, IPTV, Linux DVB, capture cards, SAT>IP, external backends and a custom command.

No dependencies

Read-only mirror of modules/wittytuner in WittyMediaServer, where development happens. Please open issues and pull requests there.

What it does

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

Driver Reaches Platforms How it has been tested
iptv M3U and M3U8 playlists (tvg-*, group-title, url-tvg) 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 boxes: UDP and SSDP discovery, discover.json, lineup.json, the scan API, MPEG-TS over HTTP all Against a mock device. Not yet on real hardware
backend TV servers over open protocols: an HTTP API with M3U and XMLTV, or SVDRP all Against stand-in servers. Not yet on a real server
satip SAT>IP servers: SSDP, RTSP tuning all Protocol tests. Untested on hardware
dvb Linux DVB-T/T2, DVB-C, DVB-S/S2, ATSC, ClearQAM, ISDB-T; band-plan scans; channels.conf import Linux Parsers and band plans tested. Untested on hardware. No DiSEqC yet
v4l2 Analogue tuner and capture cards Linux Argument tests. Untested on hardware
dshow Windows capture cards through DirectShow Windows Listing tested. Untested with a card
avfoundation macOS capture devices macOS Parser tests. Untested
command Your own program writing MPEG-TS all Automated tests with a test program
bda Windows digital tuners through BDA Not built. Listed so the gap is visible

It also reads what is in a stream: PAT, PMT, SDT, ATSC VCT, and guide data from DVB EIT and ATSC PSIP (mpegts), plus XMLTV files as they stream by (xmltv).

Encrypted and copy-protected channels

Nothing here decrypts or bypasses anything. Protected channels are detected and refused with a clear message:

  • a drm tag or DRM: 1 in a network tuner's lineup, and its "content protection required" error;
  • DTCP-IP streams, and DASH manifests with ContentProtection;
  • free_CA_mode in the SDT, CA descriptors in the PMT, access_controlled in the ATSC VCT;
  • transport_scrambling_control in the packets themselves, also mid-stream (mpegts.Guard);
  • DRM licence lines in a playlist, and any #EXT-X-KEY in an HLS playlist. FFmpeg's crypto protocol is left off its whitelist as a second lock.

wittytuner.New applies the check to every driver, so none can leave it out, and there is no hook for changing it. Channels are Checked when their source says whether they are protected, and ATSC 3.0 is an ordinary channel when it isn't encrypted (the host decides what it can decode).

No channel lists or stream addresses are included. Scans use the standard channel-to-frequency formulas, which say where a channel could be, not what is there.

Use

env := wittytuner.Env{FFmpeg: "ffmpeg"}
src, err := wittytuner.New("network", wittytuner.Config{
    Name:    "Living room",
    Options: map[string]string{"address": "192.168.1.50"},
}, env)
if err != nil { return err }

channels, err := src.Channels(ctx)
if err != nil { return err }

stream, err := src.Open(ctx, channels[0])
if err != nil { return err } // wittytuner.ErrBusy, *wittytuner.EncryptedError
defer stream.Close()
// stream.Reader is MPEG-TS, or stream.Input are options for FFmpeg.

wittytuner.Drivers(env) describes every driver and its settings, so a form can be drawn from it. wittytuner.Discover(ctx, env) looks for tuners on the network and on this machine.

The custom command driver runs a program, so it stays off unless the host sets Env.AllowCommands (WittyMediaServer: the WMS_TUNER_COMMANDS=1 environment variable).

Licence

Apache-2.0. See LICENSE and NOTICE. Developed by WittyWilla as part of WittyMediaServer.

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

Env is what a driver gets from its host.

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.

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
}

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