Documentation
¶
Overview ¶
Package player provides in-process Deezer audio playback via Player.
The audio backend is chosen at build time:
- default — miniaudio via github.com/gen2brain/malgo (adds output-device selection, works on macOS, Linux and Windows)
- build tag "otosink" — github.com/ebitengine/oto/v3 (used for the macOS GUI where malgo's CoreAudio callback is unreliable in a c-archive)
Both backends require cgo. If you only need API access, search, or download/decrypt without local playback, skip this package and use sdk/deezer alone.
Basic playback ¶
p, err := player.NewPlayer()
if err != nil { log.Fatal(err) }
defer p.Close()
plan, _ := dzClient.PrepareStream(trackID)
p.Play(plan, track.DurationMS)
// Advance when the track ends.
p.SetOnFinish(func() { queue.Advance() })
Preload for gapless transitions ¶
p.Preload(nextPlan, nextTrack.DurationMS)
Volume and ReplayGain ¶
p.SetVolume(0.8) // 80 % p.SetReplayGain(true) // loudness normalisation using the track's gain
Index ¶
- func EQPresetNames() []string
- type Device
- type Player
- func (pl *Player) CancelSleepTimer()
- func (pl *Player) Close()
- func (pl *Player) CrossfadeMS() int
- func (pl *Player) CurrentDevice() string
- func (pl *Player) Devices() ([]Device, error)
- func (pl *Player) DurationMS() int64
- func (pl *Player) EQBands() []float64
- func (pl *Player) EQEnabled() bool
- func (pl *Player) EQGains() []float64
- func (pl *Player) EQPreampDB() float64
- func (pl *Player) EQPreset() string
- func (pl *Player) Format() string
- func (pl *Player) Gapless() bool
- func (pl *Player) LastError() string
- func (pl *Player) MonoDownmix() bool
- func (pl *Player) Pause()
- func (pl *Player) Play(plan *sdkdeezer.StreamPlan, durationMS int64) error
- func (pl *Player) PositionMS() int64
- func (pl *Player) Preload(plan *sdkdeezer.StreamPlan, durationMS int64)
- func (pl *Player) ReplayGain() bool
- func (pl *Player) Resume()
- func (pl *Player) SeekMS(ms int64)
- func (pl *Player) SetCrossfadeMS(ms int)
- func (pl *Player) SetDevice(id string) error
- func (pl *Player) SetEQEnabled(on bool)
- func (pl *Player) SetEQGain(band int, db float64) error
- func (pl *Player) SetEQGains(db []float64) error
- func (pl *Player) SetEQPreamp(db float64)
- func (pl *Player) SetEQPreset(name string) error
- func (pl *Player) SetGapless(on bool)
- func (pl *Player) SetMonoDownmix(on bool)
- func (pl *Player) SetOnFinish(fn func())
- func (pl *Player) SetReplayGain(on bool)
- func (pl *Player) SetSleepTimer(d time.Duration, endOfTrack bool)
- func (pl *Player) SetVolume(v float64)
- func (pl *Player) SleepActive() bool
- func (pl *Player) SleepEndOfTrack() bool
- func (pl *Player) SleepRemainingMS() int64
- func (pl *Player) State() State
- func (pl *Player) Stop()
- func (pl *Player) TogglePause()
- func (pl *Player) Volume() float64
- type State
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EQPresetNames ¶ added in v1.7.0
func EQPresetNames() []string
EQPresetNames lists the built-in equalizer presets, in display order. "custom" is implicit: any manual band edit switches the preset to it.
Types ¶
type Device ¶
type Device = internalaudio.Device
Device is an audio output device the user can select.
- ID — opaque id passed to Player.SetDevice; "" = system default
- Name — human-readable display name
- IsDefault — true if this is the system default device
type Player ¶
type Player struct {
// contains filtered or unexported fields
}
Player streams, decrypts, decodes (MP3 + FLAC) and plays Deezer audio with gapless/crossfade transitions, ReplayGain normalisation, and output-device selection.
Create one with NewPlayer. A Player must be closed with Player.Close when no longer needed; it owns an audio output device for its lifetime.
All methods are safe for concurrent use.
func NewPlayer ¶
NewPlayer initialises the audio output device and starts the playback engine. Returns an error if no audio output is available (e.g. headless server).
func (*Player) CancelSleepTimer ¶ added in v1.6.0
func (pl *Player) CancelSleepTimer()
CancelSleepTimer disarms the sleep timer and restores full volume.
func (*Player) Close ¶
func (pl *Player) Close()
Close stops playback, releases sources, and closes the audio output device. The Player must not be used after Close.
func (*Player) CrossfadeMS ¶
CrossfadeMS returns the current crossfade duration in milliseconds.
func (*Player) CurrentDevice ¶
CurrentDevice returns the id of the currently selected output device, or "" for the system default.
func (*Player) Devices ¶
Devices lists the available audio output devices. The returned slice always includes the system default (ID == "").
func (*Player) DurationMS ¶
DurationMS returns the current track's duration in milliseconds.
func (*Player) EQBands ¶ added in v1.7.0
EQBands returns the band center frequencies in Hz (31.5 Hz .. 16 kHz).
func (*Player) EQPreampDB ¶ added in v1.7.0
EQPreampDB returns the preamp in dB.
func (*Player) EQPreset ¶ added in v1.7.0
EQPreset returns the current preset name ("custom" after manual edits).
func (*Player) Format ¶
Format returns the actual stream format of the current track (e.g. "FLAC", "MP3_320"), or "" when nothing is playing.
func (*Player) LastError ¶
LastError returns the most recent download or decode error message, or "" if none.
func (*Player) MonoDownmix ¶ added in v1.7.0
MonoDownmix reports whether mono downmix is on.
func (*Player) Play ¶
func (pl *Player) Play(plan *sdkdeezer.StreamPlan, durationMS int64) error
Play starts playing plan immediately, replacing any current track. plan must come from sdk/deezer.Client.PrepareStream or sdk/deezer.Client.PodcastEpisodeStream. durationMS is the track's duration in milliseconds (used for progress and gapless timing); pass the value from the Track metadata.
func (*Player) PositionMS ¶
PositionMS returns the playback position in milliseconds.
func (*Player) Preload ¶
func (pl *Player) Preload(plan *sdkdeezer.StreamPlan, durationMS int64)
Preload prepares the next track for a gapless or crossfaded transition. Call it shortly before the current track ends. It is a no-op when gapless and crossfade are both disabled.
func (*Player) ReplayGain ¶
ReplayGain reports whether ReplayGain normalisation is enabled.
func (*Player) Resume ¶
func (pl *Player) Resume()
Resume resumes playback after a pause (no-op if not paused).
func (*Player) SetCrossfadeMS ¶
SetCrossfadeMS sets the crossfade duration in milliseconds. 0 disables crossfade. When non-zero, the tail of the current track fades out while the next fades in.
func (*Player) SetDevice ¶
SetDevice switches the output to the given device id. Pass "" for the system default.
func (*Player) SetEQEnabled ¶ added in v1.7.0
SetEQEnabled turns the 10-band equalizer on or off (mono downmix is independent). The EQ state persists engine-side, shared by every client.
func (*Player) SetEQGain ¶ added in v1.7.0
SetEQGain sets one band's gain in dB (clamped to ±12; band 0..9). The preset becomes "custom".
func (*Player) SetEQGains ¶ added in v1.7.0
SetEQGains sets all 10 band gains in dB (clamped to ±12). The preset becomes "custom".
func (*Player) SetEQPreamp ¶ added in v1.7.0
SetEQPreamp sets the output preamp in dB (clamped to ±12), for taming clipping when several bands are boosted.
func (*Player) SetEQPreset ¶ added in v1.7.0
SetEQPreset applies a named preset (see EQPresetNames).
func (*Player) SetGapless ¶
SetGapless enables (true) or disables (false) gapless transitions. When enabled and a next source is preloaded, the transition between tracks has no silence. Default: true.
func (*Player) SetMonoDownmix ¶ added in v1.7.0
SetMonoDownmix folds stereo to mono (accessibility / single-speaker setups).
func (*Player) SetOnFinish ¶
func (pl *Player) SetOnFinish(fn func())
SetOnFinish registers a callback that is called when a track ends naturally (not when stopped or skipped). Use this to advance the queue.
func (*Player) SetReplayGain ¶
SetReplayGain enables (true) or disables (false) loudness normalisation using the per-track ReplayGain value from sdkdeezer.StreamPlan.GainDB.
func (*Player) SetSleepTimer ¶ added in v1.6.0
SetSleepTimer arms the sleep timer. With endOfTrack true, playback pauses when the current track finishes (d is ignored); otherwise it fades out over the last few seconds and pauses after d elapses. A non-positive d with endOfTrack false cancels any armed timer.
func (*Player) SleepActive ¶ added in v1.6.0
SleepActive reports whether a sleep timer is armed.
func (*Player) SleepEndOfTrack ¶ added in v1.6.0
SleepEndOfTrack reports whether the armed timer is in end-of-track mode.
func (*Player) SleepRemainingMS ¶ added in v1.6.0
SleepRemainingMS returns the milliseconds until the timer fires (0 if none).
func (*Player) TogglePause ¶
func (pl *Player) TogglePause()
TogglePause toggles between playing and paused.
type State ¶
type State = internalaudio.State
State is the player lifecycle state.
const ( // Stopped means no track is loaded. Stopped State = internalaudio.Stopped // Loading means a track is buffering before playback starts. Loading State = internalaudio.Loading // Playing means audio is being output. Playing State = internalaudio.Playing // Paused means playback is suspended. Paused State = internalaudio.Paused // Errored means a download or decode error occurred. See [Player.LastError]. Errored State = internalaudio.Errored )
Source Files