ebiten/audio/audio.go

// Copyright 2015 Hajime Hoshi
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Package audio provides audio players. This can be used with or without ebiten package.
//
// The stream format must be 16-bit little endian and 2 channels.
//
// An audio context has a sample rate you can set and all streams you want to play must have the same
// sample rate. However, decoders like audio/vorbis and audio/wav adjust sample rate,
// and you don't have to care about it as long as you use those decoders.
//
// An audio context can generate 'players' (instances of audio.Player),
// and you can play sound by calling Play function of players.
// When multiple players play, mixing is automatically done.
// Note that too many players may cause distortion.
package audio

import (
	"bytes"
	"errors"
	"io"
	"runtime"
	"sync"
	"time"

	"github.com/hajimehoshi/ebiten"
	"github.com/hajimehoshi/oto"
)

type players struct {
	players map[*Player]struct{}
	sync.RWMutex
}

const (
	channelNum     = 2
	bytesPerSample = 2

	// TODO: This assumes that channelNum is a power of 2.
	mask = ^(channelNum*bytesPerSample - 1)
)

func min(a, b int) int {
	if a < b {
		return a
	}
	return b
}

func (p *players) Read(b []uint8) (int, error) {
	p.Lock()
	defer p.Unlock()

	players := []*Player{}
	for player := range p.players {
		players = append(players, player)
	}
	if len(players) == 0 {
		l := len(b)
		l &= mask
		copy(b, make([]uint8, l))
		return l, nil
	}
	closed := []*Player{}
	l := len(b)
	for _, player := range players {
		n, err := player.readToBuffer(l)
		if err == io.EOF {
			closed = append(closed, player)
		} else if err != nil {
			return 0, err
		}
		l = min(n, l)
	}
	l &= mask
	b16s := [][]int16{}
	for _, player := range players {
		b16s = append(b16s, player.bufferToInt16(l))
	}
	for i := 0; i < l/2; i++ {
		x := 0
		for _, b16 := range b16s {
			x += int(b16[i])
		}
		if x > (1<<15)-1 {
			x = (1 << 15) - 1
		}
		if x < -(1 << 15) {
			x = -(1 << 15)
		}
		b[2*i] = byte(x)
		b[2*i+1] = byte(x >> 8)
	}
	for _, player := range players {
		player.proceed(l)
	}
	for _, pl := range closed {
		delete(p.players, pl)
	}
	return l, nil
}

func (p *players) addPlayer(player *Player) {
	p.Lock()
	p.players[player] = struct{}{}
	p.Unlock()
}

func (p *players) removePlayer(player *Player) {
	p.Lock()
	delete(p.players, player)
	p.Unlock()
}

func (p *players) hasPlayer(player *Player) bool {
	p.RLock()
	_, ok := p.players[player]
	p.RUnlock()
	return ok
}

func (p *players) hasSource(src ReadSeekCloser) bool {
	p.RLock()
	defer p.RUnlock()
	for player := range p.players {
		if player.src == src {
			return true
		}
	}
	return false
}

// A Context is a current state of audio.
//
// There should be at most one Context object.
// This means only one constant sample rate is valid in your one application.
//
// The typical usage with ebiten package is:
//
//    var audioContext *audio.Context
//
//    func update(screen *ebiten.Image) error {
//        // Update updates the audio stream by 1/60 [sec].
//        if err := audioContext.Update(); err != nil {
//            return err
//        }
//        // ...
//    }
//
//    func main() {
//        audioContext, err = audio.NewContext(sampleRate)
//        if err != nil {
//            panic(err)
//        }
//        ebiten.Run(run, update, 320, 240, 2, "Audio test")
//    }
//
// This is 'sync mode' in that game's (logical) time and audio time are synchronized.
// You can also call Update independently from the game loop as 'async mode'.
// In this case, audio goes on even when the game stops e.g. by diactivating the screen.
type Context struct {
	players         *players
	playerWriteCh   chan []uint8
	playerErrCh     chan error
	playerCloseCh   chan struct{}
	sampleRate      int
	frames          int64
	writtenBytes    int64
	discardingCount int
}

var (
	theContext     *Context
	theContextLock sync.Mutex
)

// NewContext creates a new audio context with the given sample rate (e.g. 44100).
//
// Error returned by NewContext is always nil as of 1.5.0-alpha.
//
// NewContext panics when an audio context is already created.
func NewContext(sampleRate int) (*Context, error) {
	theContextLock.Lock()
	defer theContextLock.Unlock()
	if theContext != nil {
		panic("audio: context is already created")
	}
	c := &Context{
		sampleRate: sampleRate,
	}
	theContext = c
	c.players = &players{
		players: map[*Player]struct{}{},
	}
	return c, nil

}

// Update proceeds the inner (logical) time of the context by 1/60 second.
//
// This is expected to be called in the game's updating function (sync mode)
// or an independent goroutine with timers (async mode).
// In sync mode, the game logical time syncs the audio logical time and
// you will find audio stops when the game stops e.g. when the window is deactivated.
// In async mode, the audio never stops even when the game stops.
//
// Update returns error when IO error occurs in the underlying IO object.
func (c *Context) Update() error {
	// Initialize oto.Player lazily to enable calling NewContext in an 'init' function.
	// Accessing oto.Player functions requires the environment to be already initialized,
	// but if Ebiten is used for a shared library, the timing when init functions are called
	// is unexpectable.
	// e.g. a variable for JVM on Android might not be set.
	if c.playerWriteCh == nil {
		init := make(chan error)
		c.playerWriteCh = make(chan []uint8)
		c.playerErrCh = make(chan error, 1)
		c.playerCloseCh = make(chan struct{})
		go func() {
			// The buffer size is 1/15 sec.
			// It looks like 1/20 sec is too short for Android.
			s := c.sampleRate * channelNum * bytesPerSample / 15
			p, err := oto.NewPlayer(c.sampleRate, channelNum, bytesPerSample, s)
			if err != nil {
				init <- err
				return
			}
			defer p.Close()
			close(init)
			for {
				select {
				case buf := <-c.playerWriteCh:
					if _, err = p.Write(buf); err != nil {
						c.playerErrCh <- err
					}
				case <-c.playerCloseCh:
					return
				}
			}
		}()
		if err := <-init; err != nil {
			return err
		}
	}
	select {
	case err := <-c.playerErrCh:
		close(c.playerCloseCh)
		return err
	default:
	}
	c.frames++
	bytesPerFrame := c.sampleRate * bytesPerSample * channelNum / ebiten.FPS
	l := (c.frames * int64(bytesPerFrame)) - c.writtenBytes
	l &= mask
	c.writtenBytes += l
	buf := make([]uint8, l)
	if _, err := io.ReadFull(c.players, buf); err != nil {
		close(c.playerCloseCh)
		return err
	}
	// Discard when the buffer queue seems full.
	if c.discardingCount > 0 {
		c.discardingCount--
		return nil
	}
	select {
	case c.playerWriteCh <- buf:
		// Writing can block. Don't wait for the result here.
	default:
		// The current buffer size is 1/15 [sec] = 4 [frames].
		// Wait for 5 [frames] which is more than 4.
		c.discardingCount = 5
	}
	return nil
}

// SampleRate returns the sample rate.
func (c *Context) SampleRate() int {
	return c.sampleRate
}

// ReadSeekCloser is an io.ReadSeeker and io.Closer.
type ReadSeekCloser interface {
	io.ReadSeeker
	io.Closer
}

type bytesReadSeekCloser struct {
	reader *bytes.Reader
}

func (b *bytesReadSeekCloser) Read(buf []uint8) (int, error) {
	return b.reader.Read(buf)
}

func (b *bytesReadSeekCloser) Seek(offset int64, whence int) (int64, error) {
	return b.reader.Seek(offset, whence)
}

func (b *bytesReadSeekCloser) Close() error {
	b.reader = nil
	return nil
}

// BytesReadSeekCloser creates ReadSeekCloser from bytes.
//
// A returned stream is concurrent safe.
func BytesReadSeekCloser(b []uint8) ReadSeekCloser {
	return &bytesReadSeekCloser{reader: bytes.NewReader(b)}
}

type readingResult struct {
	data []uint8
	err  error
}

// Player is an audio player which has one stream.
type Player struct {
	players    *players
	src        ReadSeekCloser
	sampleRate int
	readingCh  chan readingResult
	seekCh     chan int64

	buf    []uint8
	pos    int64
	volume float64

	srcM sync.Mutex
	m    sync.RWMutex
}

// NewPlayer creates a new player with the given stream.
//
// src's format must be linear PCM (16bits little endian, 2 channel stereo)
// without a header (e.g. RIFF header).
// The sample rate must be same as that of the audio context.
//
// Note that the given src can't be shared with other Players.
//
// NewPlayer tries to rewind src by calling Seek to get the current position.
// NewPlayer returns error when the Seek returns error.
func NewPlayer(context *Context, src ReadSeekCloser) (*Player, error) {
	if context.players.hasSource(src) {
		return nil, errors.New("audio: src cannot be shared with another Player")
	}
	p := &Player{
		players:    context.players,
		src:        src,
		sampleRate: context.sampleRate,
		seekCh:     make(chan int64, 1),
		buf:        []uint8{},
		volume:     1,
	}
	// Get the current position of the source.
	pos, err := p.src.Seek(0, io.SeekCurrent)
	if err != nil {
		return nil, err
	}
	p.pos = pos
	runtime.SetFinalizer(p, (*Player).Close)
	return p, nil
}

// NewPlayerFromBytes creates a new player with the given bytes.
//
// As opposed to NewPlayer, you don't have to care if src is already used by another player or not.
// src can be shared by multiple players.
//
// The format of src should be same as noted at NewPlayer.
//
// NewPlayerFromBytes's error is always nil as of 1.5.0-alpha.
func NewPlayerFromBytes(context *Context, src []uint8) (*Player, error) {
	b := BytesReadSeekCloser(src)
	p, err := NewPlayer(context, b)
	if err != nil {
		// Errors should never happen.
		panic(err)
	}
	return p, nil
}

// Close closes the stream. Ths source stream passed by NewPlayer will also be closed.
//
// When closing, the stream owned by the player will also be closed by calling its Close.
//
// Close is concurrent safe.
//
// Close returns error when closing the source returns error.
func (p *Player) Close() error {
	p.players.removePlayer(p)
	runtime.SetFinalizer(p, nil)
	p.srcM.Lock()
	err := p.src.Close()
	p.srcM.Unlock()
	return err
}

func (p *Player) readToBuffer(length int) (int, error) {
	if p.readingCh == nil {
		p.readingCh = make(chan readingResult)
		go func() {
			b := make([]uint8, length)
			p.srcM.Lock()
			n, err := p.src.Read(b)
			p.srcM.Unlock()
			if err != nil {
				p.readingCh <- readingResult{
					err: err,
				}
				return
			}
			p.readingCh <- readingResult{
				data: b[:n],
			}
		}()
	}
	select {
	case pos := <-p.seekCh:
		p.buf = []uint8{}
		p.pos = pos
	case r := <-p.readingCh:
		close(p.readingCh)
		p.readingCh = nil
		if r.err != nil {
			return 0, r.err
		}
		if len(r.data) > 0 {
			p.buf = append(p.buf, r.data...)
		}
	case <-timeoutIfPossible(10 * time.Millisecond):
		if l := length - len(p.buf); l > 0 {
			empty := make([]uint8, l)
			p.buf = append(p.buf, empty...)
		}
	}
	return len(p.buf), nil
}

func (p *Player) bufferToInt16(lengthInBytes int) []int16 {
	r := make([]int16, lengthInBytes/2)
	// This function must be called on the same goruotine of readToBuffer.
	if p.readingCh != nil {
		return r
	}
	p.m.RLock()
	for i := 0; i < lengthInBytes/2; i++ {
		r[i] = int16(p.buf[2*i]) | (int16(p.buf[2*i+1]) << 8)
		r[i] = int16(float64(r[i]) * p.volume)
	}
	p.m.RUnlock()
	return r
}

func (p *Player) proceed(length int) {
	// This function must be called on the same goruotine of readToBuffer.
	if p.readingCh != nil {
		return
	}
	p.buf = p.buf[length:]
	p.pos += int64(length)
}

// Play plays the stream.
//
// Play always returns nil.
//
// Play is concurrent safe.
func (p *Player) Play() error {
	p.players.addPlayer(p)
	return nil
}

// IsPlaying returns boolean indicating whether the player is playing.
//
// IsPlaying is concurrent safe.
func (p *Player) IsPlaying() bool {
	return p.players.hasPlayer(p)
}

// Rewind rewinds the current position to the start.
//
// Rewind is concurrent safe.
//
// Rewind returns error when seeking the source returns error.
func (p *Player) Rewind() error {
	return p.Seek(0)
}

// Seek seeks the position with the given offset.
//
// Seek is concurrent safe.
//
// Seek returns error when seeking the source returns error.
func (p *Player) Seek(offset time.Duration) error {
	o := int64(offset) * bytesPerSample * channelNum * int64(p.sampleRate) / int64(time.Second)
	o &= mask
	p.srcM.Lock()
	pos, err := p.src.Seek(o, io.SeekStart)
	p.srcM.Unlock()
	if err != nil {
		return err
	}
	// When the player p is not playing, as readToBuffer is never called,
	// seekCh will never solved.
	// Solve the current seeking here if necessary.
	select {
	case pos := <-p.seekCh:
		p.buf = []uint8{}
		p.pos = pos
	default:
	}
	p.seekCh <- pos
	return nil
}

// Pause pauses the playing.
//
// Pause is concurrent safe.
//
// Pause always returns nil.
func (p *Player) Pause() error {
	p.players.removePlayer(p)
	return nil
}

// Current returns the current position.
//
// Current is concurrent safe.
func (p *Player) Current() time.Duration {
	p.m.RLock()
	sample := p.pos / bytesPerSample / channelNum
	t := time.Duration(sample) * time.Second / time.Duration(p.sampleRate)
	p.m.RUnlock()
	return t
}

// Volume returns the current volume of this player [0-1].
//
// Volume is concurrent safe.
func (p *Player) Volume() float64 {
	p.m.RLock()
	v := p.volume
	p.m.RUnlock()
	return v
}

// SetVolume sets the volume of this player.
// volume must be in between 0 and 1. This function panics otherwise.
//
// SetVolume is concurrent safe.
func (p *Player) SetVolume(volume float64) {
	p.m.Lock()
	defer p.m.Unlock()
	// The condition must be true when volume is NaN.
	if !(0 <= volume && volume <= 1) {
		panic("audio: volume must be in between 0 and 1")
	}
	p.volume = volume
}