oto

README

Oto (音)

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

Platforms

• Windows
• macOS
• Linux
• FreeBSD
• Android
• iOS
• (Modern) web browsers (powered by GopherJS)

Prerequisite

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.

FreeBSD

OpenAL is required. Install openal-soft:

pkg install openal-soft

Documentation

Overview

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

Index

• type Player
  • func NewPlayer(sampleRate, channelNum, bytesPerSample, bufferSizeInBytes int) (*Player, error)
  • func (p *Player) Close() error
  • func (p *Player) SetUnderrunCallback(f func())
  • func (p *Player) Write(data []byte) (int, error)

Types

type Player

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

Player is a PCM (pulse-code modulation) audio player. It implements io.Writer, use Write method to play samples.

func NewPlayer

func NewPlayer(sampleRate, channelNum, bytesPerSample, bufferSizeInBytes int) (*Player, error)

NewPlayer creates a new, ready-to-use Player.

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 bytesPerSample 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 Player. This means, how many bytes can Player remember before actually playing them. Bigger buffer can reduce the number of 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 (*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) SetUnderrunCallback

func (p *Player) SetUnderrunCallback(f func())

SetUnderrunCallback sets a function which will be called whenever an underrun occurs. This is mostly for debugging and optimization purposes.

Underrun occurs when not enough samples is written to the player in a certain amount of time and thus there's nothing to play. This usually happens when there's too much audio data processing, or the audio data processing code gets stuck for a while, or the player's buffer is too small.

Example:

player.SetUnderrunCallback(func() {
    log.Println("UNDERRUN, YOUR CODE IS SLOW")
})

Supported platforms: Linux.

func (*Player) Write

func (p *Player) Write(data []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.