api

package
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: 31 Imported by: 0

Documentation

Overview

Package api is WittyTuner's own HTTP API (module API 5): the routes WittyMediaServer passes to it at /api/modules/wittytuner/... once it has checked who may call them (integration.json), the sources of its SDUI pages, its lifecycle, and the service's own routes the server opens channels through (stream.go). It keeps the tuners, their channels and the guide sources in WittyTuner's own database (package store), and asks the server, through the host API, only what only the server has: its FFmpeg, where to keep a guide, and that a first-run step is done.

What stays the server's: the guide and its programmes, recordings, favourites and sets, live TV's streams and their HLS, and the guard every stream passes through. The server never takes this module's word that a channel is clear.

Index

Constants

View Source
const (
	HealthOK      = "ok"
	HealthFailing = "failing"
)

What a channel's last check or tune found.

View Source
const (
	SecurityClear     = "clear"
	SecurityEncrypted = "encrypted"
	SecurityUnknown   = "unknown"
)

What is known about a channel's protection.

View Source
const DataEnv = "WITTYMODULE_DATA"

DataEnv is where the server says WittyTuner's own folder is.

View Source
const EncryptedHelpURL = "/api/modules/wittytuner/encrypted-help"

EncryptedHelpURL is where the apps open the encrypted-channels page's content.

View Source
const HeaderMachine = "X-Witty-Machine"

HeaderMachine is "1" on a request from the server's own machine.

View Source
const Masked = "••••••••"

Masked replaces passwords when options go to a browser.

View Source
const MaxBulk = 20000

MaxBulk is how many channels one bulk edit may name.

Variables

View Source
var ErrBusy = tuner.ErrBusy

ErrBusy: every tuner of a source is in use.

View Source
var ErrNoArchive = errors.New("that isn't in this channel's archive")

ErrNoArchive: what was asked for isn't in the source's archive.

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound: no such tuner, channel or guide source.

Functions

func Busy

func Busy() bool

Busy says a stream, scan or channel check is going on, so the server leaves the service running.

func DoctorCheck

func DoctorCheck(ctx context.Context, _ json.RawMessage, _ []json.RawMessage) ([]any, any, error)

DoctorCheck answers the service call doctor.Check.

func Lifecycle

func Lifecycle(ctx context.Context, call string, args wittymodule.LifecycleArgs) error

Lifecycle answers the server's lifecycle calls (integration.json). Taken off without keeping its data, WittyTuner's folder goes: its tuners, channels and guide sources. The server's own guide, recordings and sets stay the server's.

func PublicError

func PublicError(err error) string

PublicError is what people may be told about a tuner or stream that failed. Connection errors say what's on the network, and hold the address, which can hold a login. Anything else that quotes an address, as a program's errors can, has it taken out.

func PublicOptions

func PublicOptions(t *Tuner) map[string]string

PublicOptions hides passwords.

func Routes

func Routes(mux *http.ServeMux)

Routes are the module's routes, as integration.json lists them. The server has checked who is asking before it passes a request on; each is checked again here.

func SDUIItems

func SDUIItems(req sdui.ItemsRequest) (sdui.ItemsAnswer, error)

SDUIItems answers the server's sdui.items call for WittyTuner's sources.

func ServerRoutes

func ServerRoutes(mux *http.ServeMux)

ServerRoutes are the service's own routes for the server (service.Config.Routes): never a person's, so they aren't in integration.json, and only the server has the service's secret.

func Stop

func Stop()

Stop ends what the service runs, as the server goes.

func Use

func Use(m *Manager)

Use makes m the Manager the routes use, for tests.

func Warm

func Warm()

Warm opens the database and starts the guide refresher as the service starts, so guide sources are read on their schedule whenever the server has the service running.

Types

type Brand

type Brand struct {
	Kind string `json:"kind"`
	Name string `json:"name"`
}

Brand is a logo by its kind and name, in the server's logo service.

type Channel

type Channel struct {
	ID        int64  `json:"id"`
	TunerID   int64  `json:"tunerId"`
	SourceID  string `json:"sourceId"`
	Number    string `json:"number"`
	Name      string `json:"name"`
	Group     string `json:"group,omitempty"`
	CallSign  string `json:"callsign,omitempty"`
	HD        bool   `json:"hd,omitempty"`
	Radio     bool   `json:"radio,omitempty"`
	Encrypted string `json:"encrypted,omitempty"`
	// Security is encrypted, clear or unknown (nobody can tell until it is tuned).
	Security   string `json:"security"`
	ATSC3      bool   `json:"atsc3,omitempty"`
	VideoCodec string `json:"videoCodec,omitempty"`
	AudioCodec string `json:"audioCodec,omitempty"`
	// NoRecord is why this channel may not be recorded: the device said so, or
	// the owner did from what the device's documentation says.
	NoRecord  string `json:"noRecord,omitempty"`
	Program   int    `json:"program,omitempty"`
	Enabled   bool   `json:"enabled"`
	EPGID     string `json:"epgId,omitempty"`
	NumberSet string `json:"numberSet,omitempty"`
	NameSet   string `json:"nameSet,omitempty"`
	EPGSet    string `json:"epgSet,omitempty"`
	// LogoSet is what a person chose for its logo: "" to find it by name, "none", or
	// "kind|name" in the logo service.
	LogoSet string `json:"logoSet,omitempty"`
	// CatchupDays: the source keeps this many days of what the channel showed, to be
	// watched from the start. catchup and catchupSource say how to ask for it.
	CatchupDays int `json:"catchupDays,omitempty"`
	// Health is what the last check or tune found: HealthOK, HealthFailing, or "" for not yet.
	Health    string `json:"health,omitempty"`
	HealthAt  int64  `json:"healthAt,omitempty"`
	HealthMsg string `json:"healthMsg,omitempty"`
	// MergedInto: this channel is a backup of that one, hidden from the guide and tried
	// when that one won't open. Backups counts a channel's own backups (settings only).
	MergedInto int64 `json:"mergedInto,omitempty"`
	Backups    int   `json:"backups,omitempty"`
	// contains filtered or unexported fields
}

Channel is a tuner's channel as the guide and the settings see it. Number and Name are what the viewer sees: the owner's choice, else the source's.

func (*Channel) GuideKey

func (c *Channel) GuideKey() string

GuideKey is the id that links a channel to guide data.

type ChannelEdit

type ChannelEdit struct {
	Enabled *bool   `json:"enabled"`
	Number  *string `json:"number"`
	Name    *string `json:"name"`
	EPG     *string `json:"epg"`
	// NoRecord: the device's documentation says this may not be recorded.
	NoRecord *bool `json:"noRecord"`
	// CheckAgain forgets what a stream showed, for a station that has changed.
	// A channel still encrypted is refused again the next time it is tuned.
	CheckAgain bool `json:"checkAgain"`
}

ChannelEdit is what an owner may change about a channel.

type ChannelView

type ChannelView struct {
	*Channel
	LogoURL   string `json:"logoUrl,omitempty"`
	Brand     *Brand `json:"brand,omitempty"`
	CanRecord bool   `json:"canRecord"`
}

ChannelView is a channel for its settings page: as it's stored, with what it wears. The picture is the server's to serve (logoUrl, /api/tv/tun-<id>/logo), and so is the logo service a brand names.

type CheckResult

type CheckResult struct {
	Detail     string `json:"detail,omitempty"`     // what it says it is: its model and address
	MaxStreams int    `json:"maxStreams,omitempty"` // tuners in the device, or streams the provider allows
	Channels   int    `json:"channels"`
	Encrypted  int    `json:"encrypted"` // marked as protected by the source itself
	// Sample is a few channel names, so that people can see it's the source they meant.
	Sample   []string `json:"sample,omitempty"`
	OwnGuide bool     `json:"ownGuide,omitempty"` // it names guide data of its own
}

CheckResult is what a source said when asked for its channels, before it was saved.

type DupChannel

type DupChannel struct {
	ID      int64  `json:"id"`
	TunerID int64  `json:"tunerId"`
	Tuner   string `json:"tuner"`
	Number  string `json:"number"`
	Name    string `json:"name"`
	Health  string `json:"health,omitempty"`
	HD      bool   `json:"hd,omitempty"`
}

DupChannel is one channel of a group of likely duplicates.

type DupGroup

type DupGroup struct {
	Reason    string       `json:"reason"` // same guide id | same name
	Channels  []DupChannel `json:"channels"`
	Suggested int64        `json:"suggested"`
}

DupGroup is channels that look like the same station.

type EPGSource

type EPGSource struct {
	ID         int64  `json:"id"`
	Name       string `json:"name"`
	URL        string `json:"url"`
	LastFetch  *int64 `json:"lastFetch"`
	LastError  string `json:"lastError"`
	Programmes int    `json:"programmes"`
	TunerID    *int64 `json:"tunerId,omitempty"`
}

EPGSource is a place guide data comes from.

type Finding

type Finding struct {
	Check    string   `json:"check"`
	Key      string   `json:"key"`
	Severity string   `json:"severity"` // info | warn | problem
	Title    string   `json:"title"`
	What     string   `json:"what"`
	Steps    []string `json:"steps,omitempty"`
}

Finding is one thing WittyTuner's own checks found, for the server's Repair page. The server asks with the service call doctor.Check; module.json lists the checks under capabilities.doctor.

type HealthState

type HealthState struct {
	Running bool  `json:"running"`
	Done    int   `json:"done"`
	Total   int   `json:"total"`
	OK      int   `json:"ok"`
	Failing int   `json:"failing"`
	Started int64 `json:"started,omitempty"`
	// contains filtered or unexported fields
}

HealthState is how a tuner's channel check is going.

type Help

type Help struct {
	Title     string        `json:"title"`
	Sections  []HelpSection `json:"sections"`
	DevicesIn string        `json:"devicesIntro"`
	Devices   []HelpDevice  `json:"devices"`
	Checked   string        `json:"checked"` // when the device notes were checked
	Note      string        `json:"note"`
}

Help is the page behind "Encrypted: can't be played here".

func EncryptedHelp

func EncryptedHelp() Help

EncryptedHelp is the help page's content.

type HelpDevice

type HelpDevice struct {
	Name   string `json:"name"`
	Facts  string `json:"facts"`
	Source string `json:"source"`
	URL    string `json:"url"`
}

HelpDevice is one thing checked in its maker's own documentation.

type HelpSection

type HelpSection struct {
	Heading    string   `json:"heading"`
	Paragraphs []string `json:"paragraphs,omitempty"`
	Bullets    []string `json:"bullets,omitempty"`
}

HelpSection is one part of the help page.

type Manager

type Manager struct {
	DB   *store.DB
	Dir  string
	Host *host.Client // nil in tests
	Log  *slog.Logger
	// FFmpeg and FFprobe are the server's, as the host API says; "" until known.
	FFmpeg, FFprobe string
	// AllowCommands: whoever runs the machine allows the custom command driver.
	AllowCommands bool
	// contains filtered or unexported fields
}

Manager owns the tuners: their settings and channels in WittyTuner's own database, the sources running now, scans, channel checks and the guide sources.

func Get

func Get() (*Manager, error)

Get opens WittyTuner's database and reaches the server the first time something needs them.

func New

func New(db *store.DB, dir string, h *host.Client, log *slog.Logger) *Manager

New makes a manager over a database. Background work starts only when something needs it.

func (*Manager) AddSource

func (m *Manager) AddSource(ctx context.Context, name, place string) (*EPGSource, error)

AddSource adds a guide source and fetches it.

func (*Manager) AllChannels

func (m *Manager) AllChannels(ctx context.Context) ([]ServerChannel, error)

AllChannels is every channel of every tuner, with its tuner's name and state.

func (*Manager) Channel

func (m *Manager) Channel(ctx context.Context, id int64) (*Channel, error)

Channel returns one channel.

func (*Manager) Channels

func (m *Manager) Channels(ctx context.Context, tunerID int64) ([]*Channel, error)

Channels lists a tuner's channels, for settings.

func (*Manager) Check

func (m *Manager) Check(ctx context.Context, driver, name string, options map[string]string) (*CheckResult, error)

Check makes a source from these settings and asks it for its channels, without keeping anything. A source that only finds channels by scanning answers with none, which isn't a fault.

func (*Manager) CheckChannel

func (m *Manager) CheckChannel(ctx context.Context, id int64) error

CheckChannel opens a channel the way watching it would, makes sure something arrives, and keeps the answer. It takes a tuner while it runs, within the tuner's limit.

func (*Manager) Close

func (m *Manager) Close()

Close stops everything the manager runs, and every stream.

func (*Manager) Create

func (m *Manager) Create(ctx context.Context, t *Tuner) (*Tuner, error)

Create adds a tuner, checking its settings, and lists its channels. A channel list that cannot be read yet is not an error: the tuner is kept, with the reason, because the device may simply be off.

func (*Manager) Delete

func (m *Manager) Delete(ctx context.Context, id int64) error

Delete removes a tuner, its channels and its guide source.

func (*Manager) DeleteSource

func (m *Manager) DeleteSource(ctx context.Context, id int64) error

DeleteSource removes a source.

func (*Manager) Discover

func (m *Manager) Discover(ctx context.Context) ([]tuner.Found, error)

Discover looks for tuners, and leaves out those already added.

func (*Manager) Doctor

func (m *Manager) Doctor(ctx context.Context) []Finding

Doctor reports tuners and playlists whose channels failed their last health check.

func (*Manager) Drivers

func (m *Manager) Drivers(context.Context) ([]tuner.Driver, error)

Drivers lists the kinds of tuner.

func (*Manager) Duplicates

func (m *Manager) Duplicates(ctx context.Context) ([]DupGroup, error)

Duplicates finds channels, across every tuner, that look like one station: the same guide id, or failing that the same name once case, spaces and an "HD" are set aside. Channels already backing another up, and encrypted ones, are left out.

func (*Manager) EditChannel

func (m *Manager) EditChannel(ctx context.Context, id int64, e ChannelEdit) (*Channel, error)

EditChannel saves the owner's choices. They survive rescans.

func (*Manager) FetchSource

func (m *Manager) FetchSource(ctx context.Context, id int64) (err error)

FetchSource reads one source now, storing only programmes of channels on this server.

func (*Manager) GuideChannels

func (m *Manager) GuideChannels(ctx context.Context) ([]*Channel, error)

GuideChannels lists every channel that can appear in the guide, across enabled tuners. Encrypted channels stay, so people can see why they do not play.

func (*Manager) GuideIDs

func (m *Manager) GuideIDs(ctx context.Context) ([]map[string]string, error)

GuideIDs lists the guide's channel ids the server has, for mapping channels by hand.

func (*Manager) Health

func (m *Manager) Health(tunerID int64) *HealthState

Health is how a tuner's check is going, or nil if none has run.

func (*Manager) Merge

func (m *Manager) Merge(ctx context.Context, into int64, others []int64) error

Merge makes the others backups of into: hidden from the guide, and tried in turn when into won't open. Backups of the others become backups of into, so there's only ever one level.

func (*Manager) Refresh

func (m *Manager) Refresh(ctx context.Context, id int64) error

Refresh re-reads a tuner's channels without scanning.

func (*Manager) Renumber

func (m *Manager) Renumber(ctx context.Context, ids []int64, start string) error

Renumber numbers these channels from start upwards, in the order given. The numbers are the owner's own, so they stay through every new channel list.

func (*Manager) ScanProgress

func (m *Manager) ScanProgress(id int64) ScanState

ScanProgress reads a scan's state.

func (*Manager) SetAllEnabled

func (m *Manager) SetAllEnabled(ctx context.Context, tunerID int64, on bool) error

SetAllEnabled turns every channel of a tuner on or off, for long playlists.

func (*Manager) SetEnabled

func (m *Manager) SetEnabled(ctx context.Context, ids []int64, on bool) error

SetEnabled turns these channels on or off.

func (*Manager) Sources

func (m *Manager) Sources(ctx context.Context) ([]EPGSource, error)

Sources lists guide sources.

func (*Manager) Start

func (m *Manager) Start()

Start runs the guide refresher, if there is anything for it to do. Called when the service starts and whenever a tuner or a guide source is added.

func (*Manager) StartHealth

func (m *Manager) StartHealth(tunerID int64) error

StartHealth checks every enabled channel of a tuner, a few at a time and in the background. Starting it again while it runs changes nothing.

func (*Manager) StartScan

func (m *Manager) StartScan(id int64, source string) error

StartScan begins a scan in the background.

func (*Manager) StopHealth

func (m *Manager) StopHealth(tunerID int64)

StopHealth ends a tuner's check.

func (*Manager) TestChannel

func (m *Manager) TestChannel(ctx context.Context, tunerID, channelID int64) (*TestResult, error)

TestChannel tunes one of a tuner's channels for a few seconds, as a viewer would, and says what arrived. channelID 0 picks one. Nothing is kept but what the stream showed about itself, which Open's guard notes as it always does.

func (*Manager) Tuner

func (m *Manager) Tuner(ctx context.Context, id int64) (*Tuner, error)

Tuner returns one tuner.

func (*Manager) Tuners

func (m *Manager) Tuners(ctx context.Context) ([]*Tuner, error)

Tuners lists every tuner.

func (*Manager) Unmerge

func (m *Manager) Unmerge(ctx context.Context, ids []int64) error

Unmerge brings these channels back as channels of their own.

func (*Manager) Update

func (m *Manager) Update(ctx context.Context, id int64, name string, options map[string]string, enabled bool, maxStreams int) (*Tuner, error)

Update changes a tuner's settings. A masked password keeps the stored one.

type Problem

type Problem struct {
	// Kind is settings, unreachable, not-a-tuner, unreadable, empty, encrypted, busy or other.
	Kind    string `json:"kind"`
	Message string `json:"message"`
	Hint    string `json:"hint,omitempty"`
	// HelpURL is where encrypted channels are explained.
	HelpURL string `json:"helpUrl,omitempty"`
}

Problem is why a source didn't check out, in words for the page.

func CheckProblem

func CheckProblem(driver string, err error) Problem

CheckProblem turns a failed check, or a source that couldn't read its list once saved, into words for the page. What a connection said stays out: it names what's on the network.

type ScanState

type ScanState struct {
	Running bool   `json:"running"`
	Percent int    `json:"percent"`
	Found   int    `json:"found"`
	Message string `json:"message,omitempty"`
	Error   string `json:"error,omitempty"`
	Added   int    `json:"added"`
	// What the finished scan found.
	Clear     int `json:"clear"`
	Encrypted int `json:"encrypted"`
	Unknown   int `json:"unknown"`
	// contains filtered or unexported fields
}

ScanState is a scan under way, or the last one.

type ServerChannel

type ServerChannel struct {
	*Channel
	// The tuner's: its name and kind, and whether it's on.
	TunerName    string `json:"tunerName"`
	Driver       string `json:"driver"`
	TunerEnabled bool   `json:"tunerEnabled"`
	// TunerStreams is how many channels the tuner can stream at once: the owner's limit, else the
	// device's; 0 for no known limit. Recordings that would want more are marked as conflicts.
	TunerStreams int `json:"tunerStreams,omitempty"`
	// LogoURL is the source's own address for its logo, for the server to fetch and serve.
	LogoURL string `json:"logoUrl,omitempty"`
}

ServerChannel is a channel as the server's guide, live TV and recordings see it.

type TestChannel

type TestChannel struct {
	ID     int64  `json:"id"`
	Number string `json:"number"`
	Name   string `json:"name"`
}

TestChannel is the channel a test tuned.

type TestResult

type TestResult struct {
	OK      bool         `json:"ok"`
	Channel *TestChannel `json:"channel,omitempty"`
	// Problem is why it didn't play, when it didn't.
	Problem *Problem `json:"problem,omitempty"`
	// Seconds is how long it took to get the first of the stream.
	Seconds float64 `json:"seconds"`
	Video   string  `json:"video,omitempty"` // such as "H.264, 1920×1080"
	Audio   string  `json:"audio,omitempty"`
	// Clear: the server's own guard watched enough of it to know it isn't encrypted.
	Clear bool `json:"clear,omitempty"`
}

TestResult is what tuning one channel for a few seconds showed.

type Tuner

type Tuner struct {
	ID         int64             `json:"id"`
	Driver     string            `json:"driver"`
	Name       string            `json:"name"`
	Options    map[string]string `json:"options"`
	Enabled    bool              `json:"enabled"`
	MaxStreams int               `json:"maxStreams"`
	LastScan   *int64            `json:"lastScan"`
	LastError  string            `json:"lastError"`
	Detail     string            `json:"detail"`
	Channels   int               `json:"channels"`
	Encrypted  int               `json:"encrypted"` // channels known to be protected
	Clear      int               `json:"clear"`     // channels known not to be
	InUse      int               `json:"inUse"`
}

Tuner is one configured source.

func (*Tuner) Describe

func (t *Tuner) Describe() string

Describe gives a short account of a tuner, for logs.

Jump to

Keyboard shortcuts

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