audiogo

README

简体中文 | English

audio-go

audio-go is a lightweight audio processing framework built on Go and FFmpeg. It is designed to provide developers with a simple and intuitive way to handle real-time streaming audio (e.g., WebSocket voice streams, real-time transcoding) and offline audio files.

With a highly abstracted API, you can easily implement audio format conversion, channel splitting, and multi-stream real-time synthesis without getting bogged down in complex FFmpeg command-line arguments.

✨ Key Features

• Dual-Mode Architecture:
  • Stream Mode: Powered by io.Pipe communication, specifically designed for low-latency, high-concurrency real-time scenarios.
  • File Mode: Leverages FFmpeg to efficiently process disk files with support for batch conversion.
• Multifunctional Toolbox:
  • Format Convert: Seamless conversion between various audio formats.
  • Channel Split: Split stereo audio into independent Left/Right mono channels.
  • Audio Merge: Synthesize multiple mono streams, supporting "Side-by-Side" (Stereo mapping) or "Mix" modes.
• Intelligent Resampling: Built-in aresample filter to automatically align sample rates, channel counts, and encoding formats during processing.
• Robust Error Handling: Automatically captures FFmpeg stderr output and wraps it into standard Go errors, making it easy to debug issues caused by corrupted audio or parameter mismatches.

🚀 Quick Start

Prerequisites

1. Go: 1.20+
2. FFmpeg: Ensure FFmpeg dynamic libraries or binaries are pre-installed and ffmpeg is in your system PATH. FFmpeg Official Download.

Installation

Bash

go get github.com/QuincyGao/audio-go

🛠 Usage Examples

Please refer to example/main.go

Important Usage Notes

1. Mandatory Parameters for PCM: When the input format is PCM (e.g., S16LE), you must explicitly provide the SampleRate and Channels. For other encoded formats (like MP3 or WAV), these parameters are optional as they can be automatically detected by the engine.
2. Configuration Shorthand: During audio channel splitting or merging, if both channels share the same AudioFileFormat, SampleRate and Channels, you only need to provide one configuration entry in the InputArgs or OutputArgs slice. The engine will automatically apply it to both streams.
3. Channel Limitations: Currently, the framework strictly supports the merging of two mono streams into one stereo stream, or the splitting of one stereo stream into two mono streams.

---

📐 Logical Architecture

audio-go manages communication between Go and FFmpeg processes by handling Standard Input (stdin), Standard Output (stdout), and Extended File Descriptors (ExtraFiles).

Mode	Input Channels (Go -> FFmpeg)	Output Channels (FFmpeg -> Go)	Use Case
Convert	pipe:0(Primary)	pipe:1(Left)	Real-time transcoding, resampling
Split	pipe:0(Primary)	pipe:1,pipe:3	Channel separation (e.g., extracting Left channel)
Merge	pipe:0,pipe:3	pipe:1(Left)	Voice intercom merging, BGM overlay

⚙️ Core Configuration (AudioArgs)

The configuration supports slices, allowing unique parameters to be specified for each input/output stream.

• AudioFileFormat: Supports WAV, MP3, AAC, S16LE (Raw PCM), and more.
• SampleRate: Supports any sample rate (Automatic resampling built-in).
• Channels: Supports conversion between Mono (1) and Stereo (2).

---

🤝 Contribution & Feedback

If you encounter any issues or have suggestions for new features, please feel free to submit an Issue or Pull Request.

1. Fork the project.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'feat: add new audio filter').
4. Open a Pull Request.

---

📄 License

This project is licensed under the MIT License.

Documentation

Index

• type AudioEngine
  • func NewAudioEngine(engineType AudioEngineType, config formats.AudioConfig) *AudioEngine
  • func (ae *AudioEngine) CloseInput()
  • func (ae *AudioEngine) Done()
  • func (ae *AudioEngine) ReadLeft(p []byte) (int, error)
  • func (ae *AudioEngine) ReadRight(p []byte) (int, error)
  • func (ae *AudioEngine) Start(ctx context.Context) error
  • func (ae *AudioEngine) Wait() error
  • func (ae *AudioEngine) WritePrimary(data []byte) error
  • func (ae *AudioEngine) WriteSecondary(data []byte) error
• type AudioEngineType
• type Processor

Types

type AudioEngine

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

func NewAudioEngine

func NewAudioEngine(engineType AudioEngineType,
	config formats.AudioConfig) *AudioEngine

func (*AudioEngine) CloseInput

func (ae *AudioEngine) CloseInput()

CloseInPut must close input after write done

func (*AudioEngine) Done

func (ae *AudioEngine) Done()

func (*AudioEngine) ReadLeft

func (ae *AudioEngine) ReadLeft(p []byte) (int, error)

ReadLeft read left or first channel

func (*AudioEngine) ReadRight

func (ae *AudioEngine) ReadRight(p []byte) (int, error)

ReadRight read right or second channel for split

func (*AudioEngine) Start

func (ae *AudioEngine) Start(ctx context.Context) error

func (*AudioEngine) Wait

func (ae *AudioEngine) Wait() error

func (*AudioEngine) WritePrimary

func (ae *AudioEngine) WritePrimary(data []byte) error

WritePrimary write main channel

func (*AudioEngine) WriteSecondary

func (ae *AudioEngine) WriteSecondary(data []byte) error

WriteSecondary write second channel for merge

type AudioEngineType

type AudioEngineType int

const (
	Stream AudioEngineType = iota
	File
)

type Processor

type Processor interface {
	Init(context.Context) error
	Run() error
	Wait() error
	Done()

	WriteTo(int, []byte) error
	ReadFrom(int, []byte) (int, error)
	CloseInput()
}