progress

Documentation

Index

• func ParseTarget(raw string) (scheme, address string, err error)
• func SetForceTCPListenerForTest(force bool)
• type CandidateInfo
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v any) error
• type Event
• type EventType
• type Reporter
  • func NewReporter(ctx context.Context, target string) (*Reporter, error)
  • func (r *Reporter) Close() error
  • func (r *Reporter) Emit(event Event) error
• type ResultInfo
• type SocketServer
  • func StartSocketServer(ctx context.Context, onEvent func(Event)) (*SocketServer, string, error)
  • func (s *SocketServer) Close() error
• type TrackInfo

Functions

func ParseTarget

func ParseTarget(raw string) (scheme, address string, err error)

ParseTarget parses a target string into a normalized scheme and address/path.

func SetForceTCPListenerForTest

func SetForceTCPListenerForTest(force bool)

SetForceTCPListenerForTest configures TCP listener forcing for testing.

Types

type CandidateInfo

type CandidateInfo struct {
	ID         string  `json:"id,omitempty"`
	Title      string  `json:"title"`
	Artist     string  `json:"artist,omitempty"`
	Source     string  `json:"source"`
	Duration   float64 `json:"duration_seconds,omitempty"`
	Score      int     `json:"score,omitempty"`
	WebpageURL string  `json:"url,omitempty"`
}

CandidateInfo describes a candidate track found during search.

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder wraps json.Decoder for reading NDJSON lines.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder creates a Decoder for r.

func (*Decoder) Decode

func (d *Decoder) Decode(v any) error

Decode reads the next JSON-encoded value from its input and stores it in v.

type Event

type Event struct {
	Timestamp  time.Time      `json:"timestamp"`
	Type       EventType      `json:"type"`
	Phase      string         `json:"phase,omitempty"`
	Step       int            `json:"step,omitempty"`
	TotalSteps int            `json:"total_steps,omitempty"`
	Message    string         `json:"message,omitempty"`
	Percent    float64        `json:"percent,omitempty"`
	Track      *TrackInfo     `json:"track,omitempty"`
	Candidate  *CandidateInfo `json:"candidate,omitempty"`
	Result     *ResultInfo    `json:"result,omitempty"`
	Error      string         `json:"error,omitempty"`
}

Event represents an atomic structured telemetry/progress update sent over the socket.

type EventType

type EventType string

EventType represents the category of a progress event.

const (
	EventPhaseStart        EventType = "phase_start"
	EventCandidateFound    EventType = "candidate_found"
	EventCandidateSelected EventType = "candidate_selected"
	EventProgress          EventType = "progress"
	EventComplete          EventType = "complete"
	EventError             EventType = "error"
	EventTrackStart        EventType = "track_start"
	EventTrackComplete     EventType = "track_complete"
)

type Reporter

type Reporter struct {
	// contains filtered or unexported fields
}

Reporter handles streaming progress events to a socket, file descriptor, or stream.

func NewReporter

func NewReporter(ctx context.Context, target string) (*Reporter, error)

NewReporter connects to the specified progress target and returns a Reporter.

func (*Reporter) Close

func (r *Reporter) Close() error

Close gracefully closes the socket or file descriptor connection if applicable.

func (*Reporter) Emit

func (r *Reporter) Emit(event Event) error

Emit sends a single progress event as an NDJSON line. Thread-safe and nil-safe.

type ResultInfo

type ResultInfo struct {
	Path            string  `json:"path"`
	Title           string  `json:"title,omitempty"`
	Artist          string  `json:"artist,omitempty"`
	Album           string  `json:"album,omitempty"`
	ReleaseYear     string  `json:"release_year,omitempty"`
	Duration        float64 `json:"duration_seconds,omitempty"`
	BandwidthHz     int     `json:"bandwidth_hz,omitempty"`
	BandwidthRating string  `json:"bandwidth_rating,omitempty"`
	SuggestedGainDb float64 `json:"suggested_gain_db,omitempty"`
	Status          string  `json:"status,omitempty"`
}

ResultInfo describes the final artifact and quality verification metrics.

type SocketServer

type SocketServer struct {
	// contains filtered or unexported fields
}

SocketServer receives progress events from a child process over a socket (UNIX or TCP).

func StartSocketServer

func StartSocketServer(ctx context.Context, onEvent func(Event)) (*SocketServer, string, error)

StartSocketServer creates a progress socket listener. On POSIX systems, it uses a UNIX domain socket. On Windows or if UNIX sockets fail, it falls back to a local TCP socket (127.0.0.1:0).

func (*SocketServer) Close

func (s *SocketServer) Close() error

Close gracefully stops the SocketServer, closes connections, and cleans up socket resources.

type TrackInfo

type TrackInfo struct {
	Index        int    `json:"index"`
	TotalTracks  int    `json:"total_tracks"`
	Artist       string `json:"artist"`
	Title        string `json:"title"`
	Timestamp    string `json:"timestamp,omitempty"`
	ActualFile   string `json:"actual_file,omitempty"`
	Status       string `json:"status,omitempty"`
	ErrorMessage string `json:"error,omitempty"`
}

TrackInfo describes a set-level track item.