oto

README

Oto (音)

A low-level library to play sound. This package offers io.WriteCloser to play PCM sound.

Platforms

• Windows
• macOS
• Linux
• FreeBSD
• OpenBSD
• Android
• iOS
• Web browsers (GopherJS and WebAssembly)

Prerequisite

macOS

Oto requies AudioToolbox.framework, but this is automatically linked.

iOS

Oto requies these frameworks:

• AVFoundation.framework
• AudioToolbox.framework

Add them to "Linked Frameworks and Libraries" on your Xcode project.

Linux

libasound2-dev is required. On Ubuntu or Debian, run this command:

apt install libasound2-dev

In most cases this command must be run by root user or through sudo command.

Crosscompiling

To crosscompile, make sure the libraries for the target architecture are installed, and set CGO_ENABLED=1 as Go disables Cgo on crosscompiles by default

FreeBSD

OpenAL is required. Install openal-soft:

pkg install openal-soft

OpenBSD

OpenAL is required. Install openal:

pkg_add -r openal

Documentation

Overview

Package oto offers io.Writer to play sound on multiple platforms.

Index

• type Context
  • func NewContext(sampleRate, channelNum, bitDepthInBytes, bufferSizeInBytes int) (*Context, error)
  • func (c *Context) Close() error
  • func (c *Context) NewPlayer() *Player
• type Player
  • func (p *Player) Close() error
  • func (p *Player) Write(buf []byte) (int, error)

Types

type Context

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

Context is the main object in Oto. It interacts with the audio drivers.

To play sound with Oto, first create a context. Then use the context to create an arbitrary number of players. Then use the players to play sound.

There can only be one context at any time. Closing a context and opening a new one is allowed.

func NewContext

func NewContext(sampleRate, channelNum, bitDepthInBytes, bufferSizeInBytes int) (*Context, error)

NewContext creates a new context, that creates and holds ready-to-use Player objects.

The sampleRate argument specifies the number of samples that should be played during one second. Usual numbers are 44100 or 48000.

The channelNum argument specifies the number of channels. One channel is mono playback. Two channels are stereo playback. No other values are supported.

The bitDepthInBytes argument specifies the number of bytes per sample per channel. The usual value is 2. Only values 1 and 2 are supported.

The bufferSizeInBytes argument specifies the size of the buffer of the Context. This means, how many bytes can Context remember before actually playing them. Bigger buffer can reduce the number of Player's Write calls, thus reducing CPU time. Smaller buffer enables more precise timing. The longest delay between when samples were written and when they started playing is equal to the size of the buffer.

func (*Context) Close

func (c *Context) Close() error

Close closes the Context and its Players and frees any resources associated with it. The Context is no longer usable after calling Close.

func (*Context) NewPlayer

func (c *Context) NewPlayer() *Player

NewPlayer creates a new, ready-to-use Player belonging to the Context.

type Player

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

Player is a PCM (pulse-code modulation) audio player. Player implements io.WriteCloser. Use Write method to play samples.

func (*Player) Close

func (p *Player) Close() error

Close closes the Player and frees any resources associated with it. The Player is no longer usable after calling Close.

func (*Player) Write

func (p *Player) Write(buf []byte) (int, error)

Write writes PCM samples to the Player.

The format is as follows:

[data]      = [sample 1] [sample 2] [sample 3] ...
[sample *]  = [channel 1] ...
[channel *] = [byte 1] [byte 2] ...

Byte ordering is little endian.

The data is first put into the Player's buffer. Once the buffer is full, Player starts playing the data and empties the buffer.

If the supplied data doesn't fit into the Player's buffer, Write block until a sufficient amount of data has been played (or at least started playing) and the remaining unplayed data fits into the buffer.

Note, that the Player won't start playing anything until the buffer is full.