nativeaudio

README

nativeaudio

nativeaudio is a convenience package that provides a Go interface over native audio APIs.

The resultant output should be PCM s16le playable directly and also by github.com/hajimehoshi/oto and github.com/faiface/beep.

This package was inspired by the utter lack of audio decoders for AAC, which it turns out is a closed codec that Windows and macOS have bought licenses for.

For the moment Windows is implemented via the Media Foundation, and other platforms shell out to FFmpeg as a fallback. Unfortunately we can't link to FFmpeg without accepting the GPL, so we must take the performance hit of using a sub-process.

macOS bindings are expected to land relatively soon, however the other platforms are left as an exercise to the community.

go get git.sr.ht/~jackmordaunt/nativeaudio

package main 

import "git.sr.ht/~jackmordaunt/nativeaudio"

func main() {
        nativeaudio.Play("audio.m4a")
}

TODO

• macOS native bindings
• streaming API (current API is a buffered for simplicity)

Documentation

Overview

Package nativeaudio leverages native decoders for each supported OS to decode raw PCM data.

Where there are native APIs to call we default to invoking ffmpeg.

Windows: Media Foundation
  macOS: ffmepg (pending native bindings)
  Linux: ffmpeg

Index

• func End() error
• func FFmpegPlay(path string) error
• func Play(path string) error
• func Start() error
• type Format
  • func Decode(compressed []byte) (uncompressed []byte, format Format, err error)
  • func FFmpegDecode(by []byte) ([]byte, Format, error)
  • func FFmpegLoad(path string) ([]byte, Format, error)
  • func Load(path string) (uncompressed []byte, format Format, err error)

Functions

func End

func End() error

End cleans up platform code, if any.

func FFmpegPlay

func FFmpegPlay(path string) error

FFmpegPlay an audio file with ffplay.

ffplay -vn <path> -nodisp -autoexit

-vn: no video, -nodisp: do not launch graphical window, -autoexit: exit the process after playback is complete.

func Play

func Play(path string) error

Play an audio file exactly once, synchronously.

func Start

func Start() error

Start initializes any platform code required.

Types

type Format

type Format struct {
	SampleRate int // samples per second.
	Channels   int // number channels.
	BitDepth   int // bytes per sample.
}

Format describes the features of the associated PCM data necessary for correct playback.

func Decode

func Decode(compressed []byte) (uncompressed []byte, format Format, err error)

Decode compressed data, returning the uncompressed data as PCM data (s16le) and details about the PCM required to playback correctly.

func FFmpegDecode

func FFmpegDecode(by []byte) ([]byte, Format, error)

FFmpegDecode raw PCM with ffmpeg.

ffmpeg -f m4a -i pipe: -f s16le -

s16le is the PCM format specifier, the final dash means "pipe to stdout".

NOTE(jfm): unfortunately, some formats cannot be piped, so we will create a temporary file instead.

func FFmpegLoad

func FFmpegLoad(path string) ([]byte, Format, error)

FFmpegLoad raw PCM with ffmpeg.

ffmpeg -i <path> -f s16le -

s16le is the PCM format specifier, the final dash means "pipe to stdout".

func Load

func Load(path string) (uncompressed []byte, format Format, err error)

Load compressed data, returning the uncompressed data as PCM data (s16le) and details about the PCM required to playback correctly.