app

Documentation

Overview

Package app holds the state shared by every command (config, secrets, printer, flags), factories for API and account clients, and the hooks that let feature packages plug into each other without import cycles.

Ownership: each hook and factory is assigned by exactly one package, in its init() or in its cli.Register callback. Everyone else only calls it.

RunBatch       internal/jobs     (batch recognition)
RunExplorer    internal/tui      (audd browse and friends)
RenderResult   internal/tui      (result card; plain text until then)
EnsureRecorder internal/streams  (background stream recorder)
RestartRecorder internal/streams (restart it after a token change)
App.APIClient  internal/api      (via cli.Register; also APIClientOnce)
App.Account    internal/account  (via cli.Register)

The terminal screens read their data through two more hooks in internal/tui, which the integration assigns (until then the screens list streams from the API and show "not available" for the rest):

tui.NewFeed          tui.StoreFeed over internal/streamstore and
                     streams.RecentResults (now-playing, Streams tab)
tui.NewExplorerData  tui.DefaultExplorerData plus Recent (results
                     cache), Jobs and JobItems (jobs store)

This package imports only output, config, secrets, account, and media.

Index

• Variables
• func NotImplemented(what string) *output.Error
• func PlainResult(w io.Writer, a *App, r ResultView, details bool)
• type App
  • func New() *App
• type BatchOptions
• type BatchSummary
• type GlobalFlags
  • func (f GlobalFlags) MaxRequestsHint() string
  • func (f GlobalFlags) MaxRequestsName() string
• type ResultView

Variables

var (
	Version = defaultVersion
	Commit  = defaultCommit
	Date    = defaultDate
)

Build information, set with -ldflags "-X github.com/AudDMusic/audd-cli/internal/app.Version=…". Builds without ldflags (go install) take it from the module build information instead; see buildinfo.go.

var (
	// RunBatch recognizes many inputs as a resumable job.
	RunBatch = func(ctx context.Context, a *App, opts BatchOptions) (BatchSummary, error) {
		return BatchSummary{}, NotImplemented("batch recognition")
	}
	// RunExplorer opens the interactive explorer on a tab
	// (recent|jobs|streams|usage); "jobs/<id>" opens that job.
	// ctx is the command's: Ctrl-C cancels it, including for a job resumed
	// from the explorer.
	RunExplorer = func(ctx context.Context, a *App, tab string) error {
		return NotImplemented("the interactive explorer")
	}
	// RenderResult draws one recognition result for people.
	RenderResult = PlainResult
	// EnsureRecorder starts the background stream recorder if it should run
	// and is not running. started reports whether this call started it.
	EnsureRecorder = func(a *App) (started bool, err error) {
		return false, NotImplemented("the background stream recorder")
	}
	// RestartRecorder restarts the profile's background stream recorder,
	// if one runs, so it uses the API token stored now. restarted reports
	// whether it did.
	RestartRecorder = func(a *App) (restarted bool, err error) { return false, nil }
)

Cross-package hooks. Defaults report "not available in this build", except RenderResult, which defaults to PlainResult.

Functions

func NotImplemented

func NotImplemented(what string) *output.Error

NotImplemented is returned by hooks and factories nobody has assigned.

func PlainResult

func PlainResult(w io.Writer, a *App, r ResultView, details bool)

PlainResult is the text rendering used until a richer renderer is set.

Types

type App

type App struct {
	Cfg     *config.Config
	Profile *config.Profile
	Secrets secrets.Store
	Out     *output.Printer
	Flags   GlobalFlags
	In      io.Reader // stdin
	Now     func() time.Time

	// Factories. New sets defaults that return a not-implemented error; the
	// owning packages replace them (see the package comment).
	APIClient func() (*audd.Client, error)
	// APIClientOnce is APIClient for calls that must reach AudD at most
	// once (enterprise recognition, audd api): the client never retries a
	// request on its own. It defaults to APIClient.
	APIClientOnce func() (*audd.Client, error)
	Account       func() (account.Backend, error)
}

App is the per-invocation state. The root command fills it in before any command runs.

func New

func New() *App

New returns an App with default factories. The root command sets the rest.

type BatchOptions

type BatchOptions struct {
	Inputs         []media.Input
	Enterprise     bool
	Limit          *int // enterprise chunks per file; nil = no limit
	MaxFiles       *int // nil = no limit
	Return         string
	EnterpriseOpts map[string]string
	Concurrency    int
	DryRun         bool
	NoCache        bool
	Yes            bool
	RetryFailed    bool
	ResumeID       string
	// Resume and New answer "an identical earlier run did not finish":
	// continue that job, or start a new one. Without a terminal one of
	// them is required.
	Resume, New bool
}

BatchOptions describe a batch recognition run.

type BatchSummary

type BatchSummary struct {
	JobID                                              string
	Recognized, NoMatch, Failed, Cached, RequestsSpent int
	// RequestsReserved is the most that enterprise calls for files of
	// unknown length may have used (not counted in RequestsSpent).
	RequestsReserved int
}

BatchSummary is the outcome of a batch run. The file counts are for the whole job; RequestsSpent and RequestsReserved are this run's.

type GlobalFlags

type GlobalFlags struct {
	Token, Profile, Format string
	Fields                 []string
	Yes, Quiet, Debug      bool
	NoColor                bool
	MaxRequests            int
	// MaxRequestsFromConfig is set when MaxRequests came from the
	// max_requests setting, not --max-requests.
	MaxRequestsFromConfig bool
}

GlobalFlags are the flags every command accepts.

func (GlobalFlags) MaxRequestsHint

func (f GlobalFlags) MaxRequestsHint() string

MaxRequestsHint is how to change the ceiling, for hints.

func (GlobalFlags) MaxRequestsName

func (f GlobalFlags) MaxRequestsName() string

MaxRequestsName names where the request ceiling came from, for messages: "--max-requests 50" or "the max_requests setting (50)".

type ResultView

type ResultView struct {
	Artist, Title, Album, Label, ReleaseDate string
	ISRC, UPC, SongLink                      string
	AppleArtwork, AppleBG                    string
	Timecode                                 string
	Score                                    int
	Cached                                   bool
	// NoArt is set by --no-art: the renderer must not draw cover art.
	NoArt bool
	// Extra holds the API's own fields beyond the ones above.
	Extra map[string]any
}

ResultView is a recognition result flattened for display.