audio

Documentation

Index

• Variables
• func CleanupChunks(chunks []Chunk) error
• func DetectLoopbackDevice(ctx context.Context, ffmpegPath string) (*loopbackDevice, error)
• type CaptureMode
• type Chunk
  • func (c Chunk) Duration() time.Duration
  • func (c Chunk) String() string
• type Chunker
• type FFmpegRecorder
  • func NewFFmpegLoopbackRecorder(ctx context.Context, ffmpegPath string, opts ...RecorderOption) (*FFmpegRecorder, error)
  • func NewFFmpegMixRecorder(ctx context.Context, ffmpegPath, micDevice string, opts ...RecorderOption) (*FFmpegRecorder, error)
  • func NewFFmpegRecorder(ffmpegPath, device string, opts ...RecorderOption) (*FFmpegRecorder, error)
  • func (r *FFmpegRecorder) ListDevices(ctx context.Context) ([]string, error)
  • func (r *FFmpegRecorder) Record(ctx context.Context, duration time.Duration, output string) error
• type Recorder
• type RecorderOption
  • func WithFFmpegRunner(r ffmpegRunner) RecorderOption
  • func WithPactlRunner(r pactlRunner) RecorderOption
• type SilenceChunker
  • func NewSilenceChunker(ffmpegPath string, opts ...SilenceChunkerOption) (*SilenceChunker, error)
  • func (sc *SilenceChunker) Chunk(ctx context.Context, audioPath string) ([]Chunk, error)
• type SilenceChunkerOption
  • func WithCommandRunner(r commandRunner) SilenceChunkerOption
  • func WithFallback(c Chunker) SilenceChunkerOption
  • func WithFileRemover(f fileRemover) SilenceChunkerOption
  • func WithFileStatter(s fileStatter) SilenceChunkerOption
  • func WithMaxChunkSize(size int64) SilenceChunkerOption
  • func WithMinSilence(d time.Duration) SilenceChunkerOption
  • func WithNoiseDB(db float64) SilenceChunkerOption
  • func WithTempDirCreator(t tempDirCreator) SilenceChunkerOption
  • func WithWarnFunc(fn WarnFunc) SilenceChunkerOption
• type TimeChunker
  • func NewTimeChunker(ffmpegPath string, targetDuration, overlap time.Duration, ...) (*TimeChunker, error)
  • func (tc *TimeChunker) Chunk(ctx context.Context, audioPath string) ([]Chunk, error)
• type TimeChunkerOption
  • func WithTimeChunkerCommandRunner(r commandRunner) TimeChunkerOption
  • func WithTimeChunkerFileRemover(f fileRemover) TimeChunkerOption
  • func WithTimeChunkerTempDir(t tempDirCreator) TimeChunkerOption
• type WarnFunc

Variables

var ErrChunkTooLarge = errors.New("chunk exceeds 25MB limit")

ErrChunkTooLarge indicates a chunk exceeds the OpenAI API limit (25MB).

var ErrChunkingFailed = errors.New("audio chunking failed")

ErrChunkingFailed indicates FFmpeg failed during audio chunking.

var ErrFileNotFound = errors.New("file not found")

ErrFileNotFound indicates the specified input file does not exist.

var ErrInvalidOverlap = errors.New("overlap must be less than target duration")

ErrInvalidOverlap indicates overlap duration is invalid (>= target duration).

var ErrLoopbackNotFound = errors.New("loopback device not found")

ErrLoopbackNotFound indicates no loopback device was detected.

var ErrNoAudioDevice = errors.New("no audio input device found")

ErrNoAudioDevice indicates no audio input device was found or detected.

Functions

func CleanupChunks

func CleanupChunks(chunks []Chunk) error

CleanupChunks removes all chunk files and their parent directory. Call this after transcription is complete.

func DetectLoopbackDevice

func DetectLoopbackDevice(ctx context.Context, ffmpegPath string) (*loopbackDevice, error)

DetectLoopbackDevice attempts to find a loopback device for the current OS. Returns ErrLoopbackNotFound with installation instructions if not found.

Types

type CaptureMode

type CaptureMode int

CaptureMode defines what audio source to capture.

const (
	// CaptureMicrophone captures from the default microphone input.
	CaptureMicrophone CaptureMode = iota
	// CaptureLoopback captures system audio output (what you hear).
	CaptureLoopback
	// CaptureMix captures both microphone and system audio mixed together.
	CaptureMix
)

type Chunk

type Chunk struct {
	Path      string        // Absolute path to the chunk file.
	Index     int           // Zero-based index for ordering.
	StartTime time.Duration // Start timestamp in the source audio.
	EndTime   time.Duration // End timestamp in the source audio.
}

Chunk represents a segment of audio extracted from a larger file. The caller is responsible for cleaning up chunk files after use.

func (Chunk) Duration

func (c Chunk) Duration() time.Duration

Duration returns the length of this chunk.

func (Chunk) String

func (c Chunk) String() string

String returns a human-readable representation for logging.

type Chunker

type Chunker interface {
	// Chunk splits audioPath into multiple chunk files.
	// Returns chunks ordered by their position in the source audio.
	// The caller is responsible for cleaning up the returned chunk files.
	Chunk(ctx context.Context, audioPath string) ([]Chunk, error)
}

Chunker splits an audio file into smaller chunks suitable for transcription.

type FFmpegRecorder

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

FFmpegRecorder records audio using FFmpeg. It supports macOS (avfoundation), Linux (alsa/pulse), and Windows (dshow).

func NewFFmpegLoopbackRecorder

func NewFFmpegLoopbackRecorder(ctx context.Context, ffmpegPath string, opts ...RecorderOption) (*FFmpegRecorder, error)

NewFFmpegLoopbackRecorder creates a recorder for system audio (loopback) capture. It auto-detects the loopback device (BlackHole on macOS, PulseAudio monitor on Linux, Stereo Mix or virtual-audio-capturer on Windows). Returns ErrLoopbackNotFound with installation instructions if no device found.

func NewFFmpegMixRecorder

func NewFFmpegMixRecorder(ctx context.Context, ffmpegPath, micDevice string, opts ...RecorderOption) (*FFmpegRecorder, error)

NewFFmpegMixRecorder creates a recorder that captures both microphone and system audio. This is useful for recording video calls where you want both your voice and the remote audio. Returns ErrLoopbackNotFound if the loopback device is not available.

func NewFFmpegRecorder

func NewFFmpegRecorder(ffmpegPath, device string, opts ...RecorderOption) (*FFmpegRecorder, error)

NewFFmpegRecorder creates a new FFmpegRecorder for microphone capture. ffmpegPath must be a valid path to the FFmpeg binary. device can be empty for auto-detection, or a specific device name:

• macOS: ":0" or ":DeviceName"
• Linux: "default" or "hw:0"
• Windows: "Microphone (Realtek High Definition Audio)"

func (*FFmpegRecorder) ListDevices

func (r *FFmpegRecorder) ListDevices(ctx context.Context) ([]string, error)

ListDevices returns a list of available audio input devices. This can be used to help users select a device via --device flag.

func (*FFmpegRecorder) Record

func (r *FFmpegRecorder) Record(ctx context.Context, duration time.Duration, output string) error

Record records audio for the specified duration and writes to output. The output format is OGG Vorbis at 16kHz mono ~50kbps (optimized for voice). If device is empty, it auto-detects the default audio input device. Recording can be interrupted via context cancellation (Ctrl+C).

type Recorder

type Recorder interface {
	Record(ctx context.Context, duration time.Duration, output string) error
}

Recorder records audio from an input device to a file.

type RecorderOption

type RecorderOption func(*FFmpegRecorder)

RecorderOption configures an FFmpegRecorder.

func WithFFmpegRunner

func WithFFmpegRunner(r ffmpegRunner) RecorderOption

WithFFmpegRunner sets the FFmpeg command runner.

func WithPactlRunner

func WithPactlRunner(r pactlRunner) RecorderOption

WithPactlRunner sets the pactl command runner.

type SilenceChunker

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

SilenceChunker splits audio at detected silence points. Falls back to TimeChunker if no silences are found.

func NewSilenceChunker

func NewSilenceChunker(ffmpegPath string, opts ...SilenceChunkerOption) (*SilenceChunker, error)

NewSilenceChunker creates a SilenceChunker with functional options. If no fallback is provided, a default TimeChunker is created.

func (*SilenceChunker) Chunk

func (sc *SilenceChunker) Chunk(ctx context.Context, audioPath string) ([]Chunk, error)

Chunk splits the audio file at silence points. If no silences are found, falls back to time-based chunking.

type SilenceChunkerOption

type SilenceChunkerOption func(*SilenceChunker)

SilenceChunkerOption configures a SilenceChunker.

func WithCommandRunner

func WithCommandRunner(r commandRunner) SilenceChunkerOption

WithCommandRunner sets the command runner for SilenceChunker.

func WithFallback

func WithFallback(c Chunker) SilenceChunkerOption

WithFallback sets a custom fallback Chunker. Default: TimeChunker with 10min target, 30s overlap.

func WithFileRemover

func WithFileRemover(f fileRemover) SilenceChunkerOption

WithFileRemover sets the file remover for SilenceChunker.

func WithFileStatter

func WithFileStatter(s fileStatter) SilenceChunkerOption

WithFileStatter sets the file statter for SilenceChunker.

func WithMaxChunkSize

func WithMaxChunkSize(size int64) SilenceChunkerOption

WithMaxChunkSize sets the target maximum chunk size in bytes. Default: 20MB (with safety margin for OpenAI's 25MB limit).

func WithMinSilence

func WithMinSilence(d time.Duration) SilenceChunkerOption

WithMinSilence sets the minimum silence duration to detect. Default: 500ms.

func WithNoiseDB

func WithNoiseDB(db float64) SilenceChunkerOption

WithNoiseDB sets the silence detection threshold in dB. Lower values (more negative) detect quieter sounds as silence. Default: -30dB.

func WithTempDirCreator

func WithTempDirCreator(t tempDirCreator) SilenceChunkerOption

WithTempDirCreator sets the temp directory creator for SilenceChunker.

func WithWarnFunc

func WithWarnFunc(fn WarnFunc) SilenceChunkerOption

WithWarnFunc sets a callback for warning messages. By default, warnings are written to stderr. Set to nil to suppress.

type TimeChunker

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

TimeChunker splits audio into fixed-duration chunks with overlap. This is the fallback strategy when silence detection fails or finds no silences.

func NewTimeChunker

func NewTimeChunker(ffmpegPath string, targetDuration, overlap time.Duration, opts ...TimeChunkerOption) (*TimeChunker, error)

NewTimeChunker creates a TimeChunker with the specified parameters.

func (*TimeChunker) Chunk

func (tc *TimeChunker) Chunk(ctx context.Context, audioPath string) ([]Chunk, error)

Chunk splits the audio file into fixed-duration segments with overlap.

type TimeChunkerOption

type TimeChunkerOption func(*TimeChunker)

TimeChunkerOption configures a TimeChunker.

func WithTimeChunkerCommandRunner

func WithTimeChunkerCommandRunner(r commandRunner) TimeChunkerOption

WithTimeChunkerCommandRunner sets the command runner for TimeChunker.

func WithTimeChunkerFileRemover

func WithTimeChunkerFileRemover(f fileRemover) TimeChunkerOption

WithTimeChunkerFileRemover sets the file remover for TimeChunker.

func WithTimeChunkerTempDir

func WithTimeChunkerTempDir(t tempDirCreator) TimeChunkerOption

WithTimeChunkerTempDir sets the temp directory creator for TimeChunker.

type WarnFunc

type WarnFunc func(msg string)

WarnFunc is a callback for warning messages during chunking. Set to nil to suppress warnings, or provide a custom handler.