audio

package
v2.22.1 Latest Latest
Warning

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

 Go to latest Published: Nov 10, 2026 License: GPL-3.0 Imports: 26 Imported by: 0

Documentation

Overview

Package audio provides cross-platform audio playback using malgo.

Index

Constants

This section is empty.

Variables

View Source 
var ErrLiveStream = errors.New("not supported for live streams")

ErrLiveStream is returned for controls a live stream cannot honour, such as seeking.

View Source 
var ErrSingleTrack = errors.New("source has a single track")

ErrSingleTrack is returned when skipping tracks on a source that holds only one.

View Source 
var PlaylistExtensions = []string{".pls", ".m3u"}

PlaylistExtensions lists the playlist files kept with audio. They are not decoded: launching one plays its entries as a playlist.

View Source 
var SupportedExtensions = []string{
	".wav", ".mp3", ".ogg", ".flac",
	".vgm", ".vgz",
	".nsf", ".nsfe", ".gbs", ".hes", ".kss", ".spc",
	".mid", ".midi", ".kar", ".rmi",
}

SupportedExtensions lists every file extension long-form playback opens.

Functions

func IsStreamURL added in v2.22.0 

func IsStreamURL(path string) bool

IsStreamURL reports whether path is an http(s) URL played as a stream.

func SplitTrackPath added in v2.22.0 

func SplitTrackPath(path string) (file string, track int, ok bool)

SplitTrackPath splits a <file>/<n> single-track path of a multi-track format into the file and its 0-based track. ok is false when path is not such a path.

Types

type LongformPlaybackManager added in v2.15.0 

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

LongformPlaybackManager manages primary and background long-form audio slots. Each slot streams audio through the shared global output device via a ring-buffer prefetch goroutine — no full-file decode into RAM.

func NewLongformPlaybackManager added in v2.15.0 

func NewLongformPlaybackManager(lowPowerAudio bool) *LongformPlaybackManager

NewLongformPlaybackManager creates a new LongformPlaybackManager. lowPowerAudio selects a cheaper resampler for streaming decode on CPU-constrained platforms.

func (*LongformPlaybackManager) Pause added in v2.15.0 

func (m *LongformPlaybackManager) Pause(slot string) error

func (*LongformPlaybackManager) Play added in v2.15.0 

func (m *LongformPlaybackManager) Play(slot, path string, opts PlaybackOptions) error

func (*LongformPlaybackManager) Resume added in v2.15.0 

func (m *LongformPlaybackManager) Resume(slot string) error

func (*LongformPlaybackManager) Seek added in v2.15.0 

func (m *LongformPlaybackManager) Seek(slot string, offset time.Duration) error

func (*LongformPlaybackManager) SetChangeCallback added in v2.22.0 

func (m *LongformPlaybackManager) SetChangeCallback(fn func(slot string))

SetChangeCallback registers fn to be called with the normalized slot each time what a client sees of that slot's playback changes: a track starts playing, pauses, resumes or seeks, or its tags finish reading. It is not called for position progress or when a slot stops or drains. fn runs on the goroutine that made the change, never on the audio thread and never with a manager lock held, but it can run on an API request or a launch, so it must only hand the event on. This is not part of the PlaybackManager interface and is called at service startup.

func (*LongformPlaybackManager) SetDecodeFailureCallback added in v2.22.0 

func (m *LongformPlaybackManager) SetDecodeFailureCallback(slot string, fn func())

SetDecodeFailureCallback registers fn to be called when the track on a slot stops because it failed to decode, after the drain callback has reported it as not natural. A track that was stopped or replaced first does not count.

func (*LongformPlaybackManager) SetDrainCallback added in v2.15.0 

func (m *LongformPlaybackManager) SetDrainCallback(slot string, fn func(natural bool))

SetDrainCallback registers fn to be called when a slot drains. natural is true when the track reached EOF on its own; false when stopped or replaced. This is not part of the PlaybackManager interface and is called at service startup.

func (*LongformPlaybackManager) SetMidiSoundFontSource added in v2.22.0 

func (m *LongformPlaybackManager) SetMidiSoundFontSource(fn func() string)

SetMidiSoundFontSource registers fn to name the SoundFont each MIDI file plays through when it starts; "" plays it through the built-in FM synthesizer. It is not part of the PlaybackManager interface and is called at service startup.

func (*LongformPlaybackManager) SetNormalizeSource added in v2.22.0 

func (m *LongformPlaybackManager) SetNormalizeSource(fn func() bool)

SetNormalizeSource registers fn to say whether playback is levelled to a common loudness. Each playing source asks it as it decodes, so a change applies to what is playing. It is not part of the PlaybackManager interface and is called at service startup.

func (*LongformPlaybackManager) SetTrackMetaLimit added in v2.22.0 

func (m *LongformPlaybackManager) SetTrackMetaLimit(maxBytes int64)

SetTrackMetaLimit sets how many bytes of tag data a track may declare before its metadata is not read at all. It is not part of the PlaybackManager interface and is called at service startup.

func (*LongformPlaybackManager) SetVolume added in v2.22.0 

func (m *LongformPlaybackManager) SetVolume(slot string, volume float64) error

func (*LongformPlaybackManager) SkipTrack added in v2.22.0 

func (m *LongformPlaybackManager) SkipTrack(slot string, delta int) error

func (*LongformPlaybackManager) State added in v2.15.0 

func (m *LongformPlaybackManager) State(slot string) PlaybackState

func (*LongformPlaybackManager) Stop added in v2.15.0 

func (m *LongformPlaybackManager) Stop(slot string) error

func (*LongformPlaybackManager) TogglePause added in v2.15.0 

func (m *LongformPlaybackManager) TogglePause(slot string) error

type MalgoPlayer added in v2.9.1 

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

MalgoPlayer plays short audio via the shared malgo output device. Decoded and resampled PCM samples are cached per file path so repeated playback (e.g. scan feedback sounds) does not re-decode or re-resample; the realtime audio callback only sums already-prepared samples into the mix buffer.

A new Play call cancels the previous one-shot; only one scan sound plays at a time.

func NewMalgoPlayer added in v2.9.1 

func NewMalgoPlayer() *MalgoPlayer

NewMalgoPlayer creates a new MalgoPlayer instance.

func (*MalgoPlayer) ClearFileCache added in v2.9.1 

func (p *MalgoPlayer) ClearFileCache()

ClearFileCache clears the in-memory PCM cache, forcing subsequent PlayFile calls to re-read and re-decode from disk. Called after settings reload to pick up new files.

func (*MalgoPlayer) PlayBytes added in v2.11.0 

func (p *MalgoPlayer) PlayBytes(data []byte) error

PlayBytes plays audio from a byte slice asynchronously, detecting format from magic bytes. Supports WAV, OGG (Vorbis), MP3, and FLAC. Decoded+resampled PCM is cached by content hash so repeated plays (e.g. the embedded default scan feedback sounds) skip the decode work.

func (*MalgoPlayer) PlayFile added in v2.9.1 

func (p *MalgoPlayer) PlayFile(path string) error

PlayFile plays an audio file asynchronously, detecting format by extension. Supports WAV, MP3, OGG (Vorbis), and FLAC. Cancels any currently playing sound. Decoded+resampled PCM is cached per path so repeat plays skip the decode work.

func (*MalgoPlayer) SetVolume added in v2.11.0 

func (p *MalgoPlayer) SetVolume(volume float64)

SetVolume sets the playback volume (0.0–2.0). Applies to subsequent playback calls.

type PlaybackManager added in v2.15.0 

type PlaybackManager interface {
	Play(slot, path string, opts PlaybackOptions) error
	Stop(slot string) error
	Pause(slot string) error
	Resume(slot string) error
	TogglePause(slot string) error
	Seek(slot string, offset time.Duration) error
	// SetVolume changes the gain (0.0-2.0) of whatever is playing in slot,
	// taking effect within one output buffer. It does nothing when the slot
	// is empty.
	SetVolume(slot string, volume float64) error
	// SkipTrack moves delta tracks within a source that plays several
	// tracks back to back. It returns ErrSingleTrack for any other source.
	SkipTrack(slot string, delta int) error
	State(slot string) PlaybackState
}

PlaybackManager is the interface for managing long-form audio slots.

type PlaybackOptions added in v2.15.0 

type PlaybackOptions struct {
	// Stream is an already probed stream URL, so playing it does not
	// connect twice. nil probes http(s) paths itself.
	Stream *radio.Probe
	// Volume is the playback gain (0.0-2.0); 0 is silent.
	Volume float64
	// StartAt is how far into the track playback starts; 0 is the start.
	StartAt time.Duration
	// StartAtDuration is how long the track was when StartAt was recorded.
	// A track of another length is a different recording at the same path,
	// so it plays from the start. 0 skips the check.
	StartAtDuration time.Duration
}

PlaybackOptions configures a long-form Play call.

type PlaybackState added in v2.15.0 

type PlaybackState struct {
	// Meta is the track's tag metadata, nil until it has been read or when
	// the file has none. It never holds picture bytes.
	Meta     *trackmeta.Meta
	Path     string
	Position time.Duration
	Duration time.Duration
	Playing  bool
	Paused   bool
	// Live is set for a stream that plays in real time and cannot seek.
	Live bool
	// MultiTrack is set for a source that plays several tracks back to back,
	// which SkipTrack moves between.
	MultiTrack bool
}

PlaybackState describes the current state of a slot.

type Player added in v2.9.1 

type Player interface {
	PlayBytes(data []byte) error
	PlayFile(path string) error
	ClearFileCache()
	SetVolume(volume float64)
}

Player is the interface for audio playback, allowing tests to mock sound output.

Source Files

View all Source files

Directories

Path Synopsis
Package gme plays chiptune rips (NES .nsf/.nsfe, Game Boy .gbs, PC Engine .hes, MSX .kss and SNES .spc) by emulating the original sound hardware with Game_Music_Emu.
 Package gme plays chiptune rips (NES .nsf/.nsfe, Game Boy .gbs, PC Engine .hes, MSX .kss and SNES .spc) by emulating the original sound hardware with Game_Music_Emu.
Package midi renders Standard MIDI Files (.mid, .midi, .kar and RIFF .rmi) to stereo float audio.
 Package midi renders Standard MIDI Files (.mid, .midi, .kar and RIFF .rmi) to stereo float audio.
Package nativedec decodes MP3, FLAC and Ogg Vorbis with dr_mp3, dr_flac and stb_vorbis, single-file C decoders vendored in third_party, and AAC with libfaad (faad2) for network streams; see StreamDecoder.
 Package nativedec decodes MP3, FLAC and Ogg Vorbis with dr_mp3, dr_flac and stb_vorbis, single-file C decoders vendored in third_party, and AAC with libfaad (faad2) for network streams; see StreamDecoder.
Package radio plays internet radio: Icecast and Shoutcast streams, pls and m3u playlists of them, and audio HLS.
 Package radio plays internet radio: Icecast and Shoutcast streams, pls and m3u playlists of them, and audio HLS.
Package trackmeta reads the tags and cover art of an audio track.
 Package trackmeta reads the tags and cover art of an audio track.
Package vgm plays VGM and VGZ files, register logs of arcade, console and computer sound chips, by emulating the chips with cores from libvgm and emu2413.
 Package vgm plays VGM and VGZ files, register logs of arcade, console and computer sound chips, by emulating the chips with cores from libvgm and emu2413.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.