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
- Variables
- func Busy() bool
- func DoctorCheck(ctx context.Context, _ json.RawMessage, _ []json.RawMessage) ([]any, any, error)
- func Lifecycle(ctx context.Context, call string, args wittymodule.LifecycleArgs) error
- func PublicError(err error) string
- func PublicOptions(t *Tuner) map[string]string
- func Routes(mux *http.ServeMux)
- func SDUIItems(req sdui.ItemsRequest) (sdui.ItemsAnswer, error)
- func ServerRoutes(mux *http.ServeMux)
- func Stop()
- func Use(m *Manager)
- func Warm()
- type Brand
- type Channel
- type ChannelEdit
- type ChannelView
- type CheckResult
- type DupChannel
- type DupGroup
- type EPGSource
- type Finding
- type HealthState
- type Help
- type HelpDevice
- type HelpSection
- type Manager
- func (m *Manager) AddSource(ctx context.Context, name, place string) (*EPGSource, error)
- func (m *Manager) AllChannels(ctx context.Context) ([]ServerChannel, error)
- func (m *Manager) Channel(ctx context.Context, id int64) (*Channel, error)
- func (m *Manager) Channels(ctx context.Context, tunerID int64) ([]*Channel, error)
- func (m *Manager) Check(ctx context.Context, driver, name string, options map[string]string) (*CheckResult, error)
- func (m *Manager) CheckChannel(ctx context.Context, id int64) error
- func (m *Manager) Close()
- func (m *Manager) Create(ctx context.Context, t *Tuner) (*Tuner, error)
- func (m *Manager) Delete(ctx context.Context, id int64) error
- func (m *Manager) DeleteSource(ctx context.Context, id int64) error
- func (m *Manager) Discover(ctx context.Context) ([]tuner.Found, error)
- func (m *Manager) Doctor(ctx context.Context) []Finding
- func (m *Manager) Drivers(context.Context) ([]tuner.Driver, error)
- func (m *Manager) Duplicates(ctx context.Context) ([]DupGroup, error)
- func (m *Manager) EditChannel(ctx context.Context, id int64, e ChannelEdit) (*Channel, error)
- func (m *Manager) FetchSource(ctx context.Context, id int64) (err error)
- func (m *Manager) GuideChannels(ctx context.Context) ([]*Channel, error)
- func (m *Manager) GuideIDs(ctx context.Context) ([]map[string]string, error)
- func (m *Manager) Health(tunerID int64) *HealthState
- func (m *Manager) Merge(ctx context.Context, into int64, others []int64) error
- func (m *Manager) Refresh(ctx context.Context, id int64) error
- func (m *Manager) Renumber(ctx context.Context, ids []int64, start string) error
- func (m *Manager) ScanProgress(id int64) ScanState
- func (m *Manager) SetAllEnabled(ctx context.Context, tunerID int64, on bool) error
- func (m *Manager) SetEnabled(ctx context.Context, ids []int64, on bool) error
- func (m *Manager) Sources(ctx context.Context) ([]EPGSource, error)
- func (m *Manager) Start()
- func (m *Manager) StartHealth(tunerID int64) error
- func (m *Manager) StartScan(id int64, source string) error
- func (m *Manager) StopHealth(tunerID int64)
- func (m *Manager) TestChannel(ctx context.Context, tunerID, channelID int64) (*TestResult, error)
- func (m *Manager) Tuner(ctx context.Context, id int64) (*Tuner, error)
- func (m *Manager) Tuners(ctx context.Context) ([]*Tuner, error)
- func (m *Manager) Unmerge(ctx context.Context, ids []int64) error
- func (m *Manager) Update(ctx context.Context, id int64, name string, options map[string]string, ...) (*Tuner, error)
- type Problem
- type ScanState
- type ServerChannel
- type TestChannel
- type TestResult
- type Tuner
Constants ¶
const ( HealthOK = "ok" HealthFailing = "failing" )
What a channel's last check or tune found.
const ( SecurityClear = "clear" SecurityEncrypted = "encrypted" SecurityUnknown = "unknown" )
What is known about a channel's protection.
const DataEnv = "WITTYMODULE_DATA"
DataEnv is where the server says WittyTuner's own folder is.
const EncryptedHelpURL = "/api/modules/wittytuner/encrypted-help"
EncryptedHelpURL is where the apps open the encrypted-channels page's content.
const HeaderMachine = "X-Witty-Machine"
HeaderMachine is "1" on a request from the server's own machine.
const Masked = "••••••••"
Masked replaces passwords when options go to a browser.
const MaxBulk = 20000
MaxBulk is how many channels one bulk edit may name.
Variables ¶
var ErrBusy = tuner.ErrBusy
ErrBusy: every tuner of a source is in use.
var ErrNoArchive = errors.New("that isn't in this channel's archive")
ErrNoArchive: what was asked for isn't in the source's archive.
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 ¶
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 Routes ¶
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 ¶
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.
Types ¶
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"`
Logo string `json:"-"` // the source's address, never sent to clients: see handleTunerLogo
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.
type ChannelEdit ¶
type ChannelEdit struct {
Enabled *bool `json:"enabled"`
Number *string `json:"number"`
Name *string `json:"name"`
EPG *string `json:"epg"`
Logo *string `json:"logo"` // see Channel.LogoSet
// 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".
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 ¶
Get opens WittyTuner's database and reaches the server the first time something needs them.
func New ¶
New makes a manager over a database. Background work starts only when something needs 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) 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 ¶
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 ¶
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) DeleteSource ¶
DeleteSource removes a source.
func (*Manager) Doctor ¶
Doctor reports tuners and playlists whose channels failed their last health check.
func (*Manager) Duplicates ¶
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 ¶
EditChannel saves the owner's choices. They survive rescans.
func (*Manager) FetchSource ¶
FetchSource reads one source now, storing only programmes of channels on this server.
func (*Manager) GuideChannels ¶
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 ¶
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 ¶
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) Renumber ¶
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 ¶
ScanProgress reads a scan's state.
func (*Manager) SetAllEnabled ¶
SetAllEnabled turns every channel of a tuner on or off, for long playlists.
func (*Manager) SetEnabled ¶
SetEnabled turns these channels on or off.
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 ¶
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) StopHealth ¶
StopHealth ends a tuner's check.
func (*Manager) TestChannel ¶
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.
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 ¶
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.