voice

type DecodedPCMCallSink ¶ added in v0.4.9

type DecodedPCMCallSink interface {
	WritePCMForCall(deviceSerial string, callID uint64, samples []int16) error
}

DecodedPCMCallSink is the call-aware extension of DecodedPCMSink: it carries the CallID the decoded PCM belongs to so the live fan-out can fence a stale frame from a previous call on a reused voice-tap serial — the same cross-call audio-bleed guard sessionForWrite applies to the WAV. Wideband voice taps reuse a fixed pool of serials, so without this the live stream labels (and leaks) an old call's draining audio with the next call's talkgroup. A sink implementing this is preferred over plain WritePCM in WriteRawFrame's fan-out; sinks that don't implement it still get WritePCM.

type DecodedPCMSink ¶ added in v0.3.9

type DecodedPCMSink interface {
	WritePCM(deviceSerial string, samples []int16) error
}

DecodedPCMSink receives PCM the recorder decodes from digital vocoder frames, so live consumers (web stream, host player, tone-out) hear digital calls — not just analog ones. The composer's digital chains emit only raw vocoder frames, which fan out solely to the recorder (the lone decoder); without this tap that decoded audio never reaches the WritePCM-only live sinks. Mirrors composer.PCMSink's WritePCM but is declared here to avoid a voice → composer import cycle.

type ErrorAware ¶ added in v0.3.9

type ErrorAware interface {
	SetFrameErrors(correctedBits int)
}

ErrorAware is implemented by vocoders that can use the channel FEC corrected-bit count for the upcoming frame to drive adaptive smoothing (currently the pure-Go IMBE decoder). The recorder calls SetFrameErrors with the per-frame corrected-bit count immediately before Decode when the caller supplies it (P25 Phase 1); a vocoder that doesn't implement this simply ignores the channel error rate.

type NormalizeConfig ¶ added in v0.4.0

type NormalizeConfig struct {
	// Enabled turns normalization on. When false the recorder never
	// rewrites WAVs (the default).
	Enabled bool
	// TargetLUFS is the integrated-loudness target (e.g. -16).
	TargetLUFS float64
	// TruePeakDBTP is the true-peak ceiling in dBTP (e.g. -1.5).
	TruePeakDBTP float64
	// MaxBoostDB caps how much gain may be applied in either direction,
	// so a near-silent call doesn't amplify hiss up to the target.
	MaxBoostDB float64
}

NormalizeConfig configures per-call EBU R128 / BS.1770 loudness normalization of a finished recording. It mirrors ffmpeg's two-pass linear "loudnorm": measure the whole call's integrated loudness, apply a single linear gain toward TargetLUFS, then back the gain off if the true peak would exceed TruePeakDBTP. Pure gain — no compression — so the within-call dynamics the vocoder AGC produced are preserved.

type NullVocoder ¶

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

NullVocoder produces silence. It's the default when no IMBE / AMBE+2 decoder is available, and it is always safe to use because it doesn't touch any patented algorithm.

func NewNullVocoder(frameSize int) *NullVocoder

func (n *NullVocoder) Close() error

func (n *NullVocoder) Decode(_ []byte) ([]int16, error)

func (n *NullVocoder) FrameSize() int

func (n *NullVocoder) Name() string

func (n *NullVocoder) Reset()

type RawFrameCallSink ¶ added in v0.4.9

type RawFrameCallSink interface {
	WriteRawFrameForCall(deviceSerial string, callID uint64, vocoder string, frame []byte) error
}

RawFrameCallSink is the call-aware extension of RawFrameSink: it carries the CallID the raw frame belongs to so the live fan-out applies the same cross-call fence the decoded tap does when a voice-tap serial is reused. A sink implementing it is preferred over plain WriteRawFrame in the raw-tap fan-out; sinks that don't still get WriteRawFrame.

type RawFrameSink ¶ added in v0.4.9

type RawFrameSink interface {
	WriteRawFrame(deviceSerial, vocoder string, frame []byte) error
}

RawFrameSink receives the verbatim, un-decoded vocoder frames (IMBE / AMBE+2) the recorder also lays down as its .raw sidecar, so a live consumer — the gRPC audio publisher's include_raw subscribers — can stream the raw bytes without the recorder remaining the only place they exist. It carries the vocoder name that produced the session so the wire frame can label its codec, and unlike the decoded tap it fires even for protocols with no in-process decoder (ProVoice, encrypted): the raw bytes exist even when decoded PCM does not.

type Recorder ¶

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

Recorder writes per-call audio + raw-frame files. It subscribes to events.KindCallStart and events.KindCallEnd from the trunking engine, opens a WAV (and optional raw-frame sidecar) for each new call, and closes them on call end. The demod-pipeline composer pushes PCM samples in via WritePCM (analog protocols) and raw vocoder frames in via WriteRawFrame (digital protocols), keyed by device serial.

Layout under OutDir (Trunk-Recorder-style):

<OutDir>/<system>/<talkgroup-or-decimal-id>/<UTC-RFC3339>_freq<Hz>_src<src>.wav
<OutDir>/<system>/<talkgroup-or-decimal-id>/<UTC-RFC3339>_freq<Hz>_src<src>.raw

(The _freq<Hz> tag carries the RF voice-channel frequency; it is omitted when the grant frequency is unknown. A _ts<slot> tag is appended for slotted protocols. When per-transmission recording is enabled, each over rolls to a new file with a fresh timestamp.)

The raw sidecar is appended once per WriteRawFrame call. It is intentionally a flat concatenation of frames so users can BYO decoder (external libmbe, DVSI hardware, etc.) without parsing surrounding metadata.

Per-call vocoder: when Grant.Protocol matches an entry in the configured VocoderForProtocol map, the recorder instantiates a fresh Vocoder from voice.DefaultRegistry on CallStart and decodes each WriteRawFrame call through it, writing the resulting PCM into the WAV. This makes captures of P25 / DMR / NXDN voice produce playable WAVs alongside the optional raw sidecar — out-of-band decode via `gophertrunk decode` remains available for operators who want bit-exact mbelib / DSD-FME output.

EDACS ProVoice grants (Grant.ProVoice == true) always force a `.raw` sidecar even when WriteRaw is false. The ProVoice vocoder is patent + trade-secret encumbered so we cannot ship a built-in decoder; the sidecar lets researchers feed frames into an external decoder.

func NewRecorder(opts RecorderOptions) (*Recorder, error)

func (r *Recorder) Close() error

func (r *Recorder) HasSession(deviceSerial string) bool

func (r *Recorder) RecordingEnabled() bool

func (r *Recorder) Run(ctx context.Context) error

func (r *Recorder) SessionCount() int

func (r *Recorder) SetDecodedPCMSink(s DecodedPCMSink)

func (r *Recorder) SetRawFrameSink(s RawFrameSink)

func (r *Recorder) SetRecordingEnabled(enabled bool)

func (r *Recorder) SetVoiceEnhance(cfg mbe.EnhancerConfig)

func (r *Recorder) VoiceEnhance() mbe.EnhancerConfig

func (r *Recorder) WritePCM(deviceSerial string, samples []int16) error

func (r *Recorder) WriteRawFrame(deviceSerial string, frame []byte) error

func (r *Recorder) WriteRawFrameForCall(deviceSerial string, callID uint64, frame []byte, correctedBits int) error

func (r *Recorder) WriteRawFrameWithErrors(deviceSerial string, frame []byte, correctedBits int) error

type RecorderOptions ¶

type RecorderOptions struct {
	Bus        *events.Bus
	Log        *slog.Logger
	OutDir     string
	SampleRate uint32 // 8000 typical
	WriteRaw   bool   // emit a .raw sidecar alongside each .wav

	// SkipEncrypted, when true, makes the recorder refuse to write files
	// for calls flagged encrypted. A grant that already signals encryption
	// never opens a session; a call whose encryption is only discovered
	// mid-stream (P25 Phase 1 LDU2 Encryption Sync, or a Phase 2 compressed
	// grant resolved in-call) has its in-progress WAV/raw files closed and
	// deleted, and no CallComplete is published so downstream upload feeds
	// never see the partial.
	SkipEncrypted bool

	// Normalize configures optional per-call EBU R128 / BS.1770 loudness
	// normalization. When Enabled, a finished WAV is measured and rewritten
	// in place to TargetLUFS (true-peak limited) before CallComplete is
	// published, so every downstream consumer (web playback, MP3 encode,
	// uploads) reads the normalized audio. Off by default.
	Normalize NormalizeConfig

	// Enhance configures the optional, opt-in "sound-good" voice
	// enhancement chain (band-limit + warmth shelf + louder AGC +
	// optional compression) applied to decoded digital voice. When
	// Enabled it shapes both the recorded WAV and the live decoded-PCM
	// fan-out, since both come from the recorder's single per-call
	// vocoder. Disabled by default (faithful, byte-identical output).
	Enhance mbe.EnhancerConfig

	// VocoderForProtocol maps a Grant.Protocol value to a vocoder
	// registry name used to decode raw frames into PCM that's
	// written to the call's WAV. nil means "use the package
	// defaults" (DefaultVocoderForProtocol). Pass an explicit empty
	// (non-nil) map to disable auto-decode entirely; the .raw
	// sidecar then becomes the only path for digital voice.
	//
	// Protocols not in the map produce no decoded audio — typically
	// analog protocols (motorola, edacs, ltr, mpt1327) where the
	// composer's FM chain feeds WritePCM directly, and ProVoice
	// where no in-binary decoder is available.
	VocoderForProtocol map[string]string

	// DisplayLoc is the timezone the recording-filename timestamp renders
	// in (display.timezone, via config.DisplayConfig.Location()). nil falls
	// back to time.UTC (the prior behaviour). Threaded so WAV filenames
	// match the local wall-clock the rest of the UI/logs already show,
	// instead of always UTC.
	DisplayLoc *time.Location
}

RecorderOptions configure a new Recorder.

type Registry ¶

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

Registry holds the set of vocoders the running daemon has linked in. Drivers register from init(); callers fetch by name from config.

func NewRegistry() *Registry

func (r *Registry) Names() []string

func (r *Registry) New(name string) (Vocoder, error)

func (r *Registry) Register(name string, f VocoderFactory)

type StatProvider ¶ added in v0.3.9

type StatProvider interface {
	VoiceStats() (VoiceStats, bool)
	ResetStats()
}

StatProvider is implemented by vocoders that can report a per-call VoiceStats summary (currently the pure-Go IMBE decoder). The recorder and the offline `gophertrunk decode` tool type-assert to this interface so a vocoder that doesn't track stats simply produces no summary.

VoiceStats returns the accumulated stats and ok == false when no frames have been decoded yet. ResetStats clears the accumulator (the recorder calls it at the start of each call / segment).

type Vocoder ¶

type Vocoder interface {
	Name() string
	FrameSize() int // input bytes per frame
	Decode(frame []byte) ([]int16, error)
	Reset()
	Close() error
}

Vocoder is implemented by every voice decoder GopherTrunk can use: pure-Go IMBE, pure-Go AMBE+2, the future DVSI hardware backend, and the NullVocoder used when no decoder is available.

Decode consumes one compressed frame and returns 16-bit PCM samples at 8 kHz mono (one frame is 20 ms = 160 samples for IMBE/AMBE+2). Decoders that need internal state across frames (most vocoders do) keep it on the implementation; they are NOT safe for concurrent calls on the same instance.

type VocoderFactory ¶

type VocoderFactory func() (Vocoder, error)

VocoderFactory builds a fresh vocoder instance per call. We allocate one per call so vocoders with internal state don't bleed between calls.

type VoiceEnhanceable ¶ added in v0.5.3

type VoiceEnhanceable interface {
	SetVoiceEnhancer(cfg mbe.EnhancerConfig)
}

VoiceEnhanceable is the optional interface a software vocoder implements to accept the opt-in output enhancement chain (recordings.enhance). The recorder type-asserts the vocoder it builds for each call and, when the assertion succeeds, installs the current enhancement config so the chain applies to BOTH the recorded WAV and the live decoded-PCM fan-out (they share this one decode). Vocoders that don't implement it (e.g. a future hardware backend) simply decode faithfully. The imbe and ambe2 decoders implement it.

type VoiceStats ¶ added in v0.3.9

type VoiceStats struct {
	// Frame-class counts over the call.
	Frames    int // total frames passed to Decode
	Voiced    int // frames with a majority of voiced harmonics
	Unvoiced  int // good frames with a majority of unvoiced harmonics
	Silent    int // explicit silence-window frames
	IdleMuted int // idle-carrier-tone frames muted to silence
	Bad       int // bad frames that emitted silence (cache miss / budget out)
	Repeated  int // bad frames served from the last-good repeat cache

	// Pitch / spectral envelope, averaged over good non-silent frames.
	MeanF0Hz       float64 // mean fundamental frequency (Hz)
	MinF0Hz        float64 // min fundamental seen
	MaxF0Hz        float64 // max fundamental seen
	MeanL          float64 // mean harmonic count
	MeanVoicedFrac float64 // mean fraction of harmonics that were voiced

	// AGC behaviour over the call.
	MeanAGCGain float64 // mean per-frame applied gain
	MinAGCGain  float64 // min applied gain (loudest input frames)
	MaxAGCGain  float64 // max applied gain (quietest input frames)

	// Fundamental-frequency parameter (b_0) range over all frames. b_0 is
	// the raw codebook index the IMBE header carries; the idle-carrier
	// corner is b_0 ≤ 7. When a call decodes to all-idle (Voiced+Unvoiced
	// == 0), these disambiguate a genuine low-modulation dead-key (b_0
	// varying within [0,7]) from empty/zero frames reaching the vocoder —
	// a mistuned tap or extraction bug (b_0 pinned at 0). MaxB0 == 0 with
	// frames > 0 means every frame's b_0 was 0.
	MinB0 int // smallest b_0 seen across all frames (−1 when no frames)
	MaxB0 int // largest b_0 seen across all frames (−1 when no frames)
	// FirstFrameHex is the first raw 11-byte vocoder frame as hex, captured
	// for diagnostics so an all-idle capture can be inspected off-line.
	FirstFrameHex string

	// Output amplitude health.
	MaxPreClipPeak float64 // largest pre-clip sample magnitude (int16 units)
	OutputRMS      float64 // RMS of the int16 output across the call
	CrestFactor    float64 // post-AGC peak / RMS (natural speech ~8–15)
	ClipSamples    int     // output samples hard-limited at the rail
	TotalSamples   int     // total output samples
}

VoiceStats is a compact, per-call summary of a vocoder's decode + synthesis behaviour. It exists for diagnostics: a field tester reporting "robotic" or over-loud audio can be triaged from these numbers without per-frame log spam. The decode-quality line in the composer covers the FEC layer (uncorrectable LDUs, corrected bit errors); VoiceStats covers the *audio* layer the FEC counters can't see — pitch, harmonic count, AGC gain, and (critically) whether the output is clipping or has been compressed flat.

Loudness/dynamics health is read from CrestFactor (peak/RMS): natural speech sits around 8–15, and a value near 3–4 with ClipPct > 0 is the signature of an over-hot AGC slamming every frame into the int16 rail.

All fields are aggregated across one call (one recording session / one offline decode run). Zero-frame stats are reported as Frames == 0 and should be skipped by callers.

func (s VoiceStats) ClipPct() float64

type WavWriter ¶

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

WavWriter writes a 16-bit PCM mono WAV file. Length fields in the RIFF and data chunks are patched in Close() so that a daemon crash leaves a readable (if length-zero) file behind rather than something most media players reject.

Construction takes any io.WriteSeeker (so tests can use bytes.Buffer wrapped in an in-memory seeker). The dedicated NewFile helper opens a regular file on disk.

func NewWavFile(path string, sampleRate uint32) (*WavWriter, error)

func NewWavWriter(w io.WriteSeeker, sampleRate uint32) (*WavWriter, error)

func (w *WavWriter) Close() error

func (w *WavWriter) DataBytes() uint32

func (w *WavWriter) WriteSamples(samples []int16) error