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.
//
// The stream format must be 16-bit little endian and 2 channels. The format is as follows:
//   [data]      = [sample 1] [sample 2] [sample 3] ...
//   [sample *]  = [channel 1] ...
//   [channel *] = [byte 1] [byte 2] ...
//
// An audio context (audio.Context object) has a sample rate you can specify and all streams you want to play must have the same
// sample rate. However, decoders in e.g. audio/mp3 package adjust sample rate automatically,
// and you don't have to care about it as long as you use those decoders.
//
// An audio context can generate 'players' (audio.Player objects),
// 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.
//
// For the simplest example to play sound, see wav package in the examples.
package audio

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

	"github.com/hajimehoshi/ebiten/internal/web"
)

// A Context represents a current state of audio.
//
// At most one Context object can exist in one process.
// This means only one constant sample rate is valid in your one application.
//
// For a typical usage example, see examples/wav/main.go.
type Context struct {
	c context

	mux        *mux
	sampleRate int
	err        error
	inited     bool
	suspended  bool
	ready      bool

	m sync.Mutex
}

var (
	theContext     *Context
	theContextLock sync.Mutex
)

// NewContext creates a new audio context with the given sample rate.
//
// The sample rate is also used for decoding MP3 with audio/mp3 package
// or other formats as the target sample rate.
//
// sampleRate should be 44100 or 48000.
// Other values might not work.
// For example, 22050 causes error on Safari when decoding MP3.
//
// 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,
		c:          newContext(sampleRate),
	}
	theContext = c
	c.mux = newMux()

	h := getHook()
	h.OnSuspendAudio(func() {
		c.m.Lock()
		c.suspended = true
		c.m.Unlock()
	})
	h.OnResumeAudio(func() {
		c.m.Lock()
		c.suspended = false
		c.m.Unlock()
	})

	h.AppendHookOnBeforeUpdate(func() error {
		c.m.Lock()
		c.inited = true
		c.m.Unlock()

		var err error
		theContextLock.Lock()
		if theContext != nil {
			theContext.m.Lock()
			err = theContext.err
			theContext.m.Unlock()
		}
		theContextLock.Unlock()
		return err
	})

	go c.loop()

	return c, nil
}

// CurrentContext returns the current context or nil if there is no context.
func CurrentContext() *Context {
	theContextLock.Lock()
	c := theContext
	theContextLock.Unlock()
	return c
}

func (c *Context) playable() bool {
	c.m.Lock()
	i := c.inited
	s := c.suspended
	c.m.Unlock()
	return i && !s
}

func (c *Context) setError(err error) {
	// TODO: What if c.err already exists?
	c.m.Lock()
	c.err = err
	c.m.Unlock()
}

func (c *Context) setReady() {
	c.m.Lock()
	c.ready = true
	c.m.Unlock()
}

func (c *Context) loop() {
	defer c.c.Close()

	p := c.c.NewPlayer()
	defer p.Close()

	for {
		if !c.playable() {
			runtime.Gosched()
			continue
		}
		if _, err := io.CopyN(p, c.mux, 2048); err != nil {
			c.setError(err)
			return
		}
		c.setReady()
	}
}

// IsReady returns a boolean value indicating whether the audio is ready or not.
//
// On some browsers, user interaction like click or pressing keys is required to start audio.
func (c *Context) IsReady() bool {
	c.m.Lock()
	r := c.ready
	c.m.Unlock()
	return r
}

// Update is deprecated as of 1.6.0-alpha.
//
// As of 1.6.0-alpha, Update always returns nil and does nothing related to updating the state.
// You don't have to call Update any longer.
// The internal audio error is returned at ebiten.Run instead.
func (c *Context) Update() error {
	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 []byte) (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.
func BytesReadSeekCloser(b []byte) ReadSeekCloser {
	return &bytesReadSeekCloser{reader: bytes.NewReader(b)}
}

// Player is an audio player which has one stream.
//
// Even when all references to a Player object is gone,
// the object is not GCed until the player finishes playing.
// This means that if a Player plays an infinite stream,
// the object is never GCed unless Close is called.
type Player struct {
	p *playerImpl
}

type playerImpl struct {
	mux              *mux
	src              io.ReadCloser
	srcEOF           bool
	sampleRate       int
	playing          bool
	closedExplicitly bool
	runningReadLoop  bool

	buf    []byte
	pos    int64
	volume float64

	closeCh     chan struct{}
	closedCh    chan struct{}
	seekCh      chan struct{}
	seekedCh    chan struct{}
	proceedCh   chan []int16
	proceededCh chan proceededValues
	syncCh      chan func()

	m sync.Mutex
}

type proceededValues struct {
	buf []int16
	err error
}

// 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.
//
// The player is seekable when src is io.Seeker.
// Attempt to seek the player that is not io.Seeker causes panic.
//
// Note that the given src can't be shared with other Player objects.
//
// NewPlayer tries to call Seek of src to get the current position.
// NewPlayer returns error when the Seek returns error.
//
// NewPlayer takes the ownership of src. Player's Close calls src's Close.
func NewPlayer(context *Context, src io.ReadCloser) (*Player, error) {
	p := &Player{
		&playerImpl{
			mux:         context.mux,
			src:         src,
			sampleRate:  context.sampleRate,
			buf:         nil,
			volume:      1,
			closeCh:     make(chan struct{}),
			closedCh:    make(chan struct{}),
			seekCh:      make(chan struct{}),
			seekedCh:    make(chan struct{}),
			proceedCh:   make(chan []int16),
			proceededCh: make(chan proceededValues),
		},
	}
	if seeker, ok := p.p.src.(io.Seeker); ok {
		// Get the current position of the source.
		pos, err := seeker.Seek(0, io.SeekCurrent)
		if err != nil {
			return nil, err
		}
		p.p.pos = pos
	}
	runtime.SetFinalizer(p, (*Player).finalize)

	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 []byte) (*Player, error) {
	b := BytesReadSeekCloser(src)
	p, err := NewPlayer(context, b)
	if err != nil {
		// Errors should never happen.
		panic(fmt.Sprintf("audio: %v at NewPlayerFromBytes", err))
	}
	return p, nil
}

func (p *Player) finalize() {
	runtime.SetFinalizer(p, nil)
	// TODO: It is really hard to say concurrent safety.
	// Refactor this package to reduce goroutines.
	if !p.IsPlaying() {
		p.Close()
	}
}

// Close closes the stream.
//
// When closing, the stream owned by the player will also be closed by calling its Close.
// This means that the source stream passed via NewPlayer will also be closed.
//
// Close returns error when closing the source returns error.
func (p *Player) Close() error {
	runtime.SetFinalizer(p, nil)
	return p.p.Close()
}

func (p *playerImpl) Close() error {
	p.m.Lock()
	p.playing = false
	p.mux.removePlayer(p)
	if p.closedExplicitly {
		p.m.Unlock()
		return fmt.Errorf("audio: the player is already closed")
	}
	p.closedExplicitly = true
	// src.Close is called only when Player's Close is called.
	if err := p.src.Close(); err != nil {
		p.m.Unlock()
		return err
	}
	p.m.Unlock()
	return p.closeImpl()
}

func (p *playerImpl) ensureReadLoop() error {
	p.m.Lock()
	defer p.m.Unlock()
	if p.closedExplicitly {
		return fmt.Errorf("audio: the player is already closed")
	}
	if p.runningReadLoop {
		return nil
	}

	// Set runningReadLoop true here, not in the loop, or this causes deadlock with channels in Seek.
	// While the for loop doesn't start, Seeks tries to send something to the channels.
	// The for loop must start without any locking.
	p.runningReadLoop = true
	go p.readLoop()
	return nil
}

func (p *playerImpl) closeImpl() error {
	p.m.Lock()
	r := p.runningReadLoop
	p.m.Unlock()
	if !r {
		return nil
	}

	p.closeCh <- struct{}{}
	<-p.closedCh
	return nil
}

func (p *playerImpl) bufferToInt16(lengthInBytes int) ([]int16, error) {
	if err := p.ensureReadLoop(); err != nil {
		return nil, err
	}
	p.proceedCh <- make([]int16, lengthInBytes/2)
	r := <-p.proceededCh
	return r.buf, r.err
}

// Play plays the stream.
//
// Play always returns nil.
func (p *Player) Play() error {
	p.p.Play()
	return nil
}

func (p *playerImpl) Play() {
	p.m.Lock()
	p.playing = true
	p.mux.addPlayer(p)
	p.m.Unlock()
}

func (p *playerImpl) readLoop() {
	defer func() {
		p.m.Lock()
		p.playing = false
		p.runningReadLoop = false
		p.m.Unlock()
	}()

	timer := time.NewTimer(0)
	timerCh := timer.C
	var readErr error
	for {
		select {
		case <-p.closeCh:
			p.closedCh <- struct{}{}
			return

		case <-p.seekCh:
			p.seekedCh <- struct{}{}
			if timer != nil {
				timer.Stop()
			}
			timer = time.NewTimer(time.Millisecond)
			timerCh = timer.C

		case <-timerCh:
			// If the buffer has 1 second, that's enough.
			p.m.Lock()
			if len(p.buf) >= p.sampleRate*bytesPerSample {
				if timer != nil {
					timer.Stop()
				}
				timer = time.NewTimer(100 * time.Millisecond)
				timerCh = timer.C
				p.m.Unlock()
				break
			}

			// Try to read the buffer for 1/60[s].
			s := 60
			if web.IsAndroidChrome() {
				s = 10
			} else if web.IsBrowser() {
				s = 20
			}
			l := p.sampleRate * bytesPerSample / s
			l &= mask
			buf := make([]byte, l)
			n, err := p.src.Read(buf)

			p.buf = append(p.buf, buf[:n]...)
			if err == io.EOF {
				p.srcEOF = true
			}
			if p.srcEOF && len(p.buf) == 0 {
				if timer != nil {
					timer.Stop()
				}
				timer = nil
				timerCh = nil
				p.m.Unlock()
				break
			}
			p.m.Unlock()

			if err != nil && err != io.EOF {
				readErr = err
				if timer != nil {
					timer.Stop()
				}
				timer = nil
				timerCh = nil
				break
			}
			if timer != nil {
				timer.Stop()
			}
			if web.IsBrowser() {
				timer = time.NewTimer(10 * time.Millisecond)
			} else {
				timer = time.NewTimer(time.Millisecond)
			}
			timerCh = timer.C

		case buf := <-p.proceedCh:
			if readErr != nil {
				p.proceededCh <- proceededValues{buf, readErr}
				return
			}

			p.m.Lock()
			if p.shouldSkipImpl() {
				// Return zero values.
				p.proceededCh <- proceededValues{buf, nil}
				p.m.Unlock()
				break
			}

			lengthInBytes := len(buf) * 2
			l := lengthInBytes

			if l > len(p.buf) {
				l = len(p.buf)
			}
			for i := 0; i < l/2; i++ {
				buf[i] = int16(p.buf[2*i]) | (int16(p.buf[2*i+1]) << 8)
				buf[i] = int16(float64(buf[i]) * p.volume)
			}
			p.pos += int64(l)
			p.buf = p.buf[l:]
			p.m.Unlock()

			p.proceededCh <- proceededValues{buf[:l/2], nil}
		}
	}
}

func (p *playerImpl) shouldSkip() bool {
	p.m.Lock()
	r := p.shouldSkipImpl()
	p.m.Unlock()
	return r
}

func (p *playerImpl) shouldSkipImpl() bool {
	// When p.buf is nil, the player just starts playing or seeking.
	// Note that this is different from len(p.buf) == 0 && p.buf != nil.
	if p.buf == nil {
		return true
	}
	if p.eofImpl() {
		return true
	}
	return false
}

func (p *playerImpl) bufferSizeInBytes() int {
	p.m.Lock()
	s := len(p.buf)
	p.m.Unlock()
	return s
}

func (p *playerImpl) eof() bool {
	p.m.Lock()
	r := p.eofImpl()
	p.m.Unlock()
	return r
}

func (p *playerImpl) eofImpl() bool {
	return p.srcEOF && len(p.buf) == 0
}

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

func (p *playerImpl) IsPlaying() bool {
	p.m.Lock()
	r := p.playing
	p.m.Unlock()
	return r
}

// Rewind rewinds the current position to the start.
//
// The passed source to NewPlayer must be io.Seeker, or Rewind panics.
//
// Rewind returns error when seeking the source stream returns error.
func (p *Player) Rewind() error {
	return p.p.Rewind()
}

func (p *playerImpl) Rewind() error {
	if _, ok := p.src.(io.Seeker); !ok {
		panic("audio: player to be rewound must be io.Seeker")
	}
	return p.Seek(0)
}

// Seek seeks the position with the given offset.
//
// The passed source to NewPlayer must be io.Seeker, or Seek panics.
//
// Seek returns error when seeking the source stream returns error.
func (p *Player) Seek(offset time.Duration) error {
	return p.p.Seek(offset)
}

func (p *playerImpl) Seek(offset time.Duration) error {
	if _, ok := p.src.(io.Seeker); !ok {
		panic("audio: player to be sought must be io.Seeker")
	}
	if err := p.ensureReadLoop(); err != nil {
		return err
	}

	p.m.Lock()
	defer p.m.Unlock()

	o := int64(offset) * bytesPerSample * int64(p.sampleRate) / int64(time.Second)
	o &= mask

	seeker, ok := p.src.(io.Seeker)
	if !ok {
		panic("audio: the source must be io.Seeker when seeking")
	}
	pos, err := seeker.Seek(o, io.SeekStart)
	if err != nil {
		return err
	}

	p.buf = nil
	p.pos = pos
	p.srcEOF = false
	p.seekCh <- struct{}{}
	<-p.seekedCh
	return nil
}

// Pause pauses the playing.
//
// Pause always returns nil.
func (p *Player) Pause() error {
	p.p.Pause()
	return nil
}

func (p *playerImpl) Pause() {
	p.m.Lock()
	p.playing = false
	p.mux.removePlayer(p)
	p.m.Unlock()
}

// Current returns the current position.
func (p *Player) Current() time.Duration {
	return p.p.Current()
}

func (p *playerImpl) Current() time.Duration {
	p.m.Lock()
	sample := p.pos / bytesPerSample
	p.m.Unlock()
	return time.Duration(sample) * time.Second / time.Duration(p.sampleRate)
}

// Volume returns the current volume of this player [0-1].
func (p *Player) Volume() float64 {
	return p.p.Volume()
}

func (p *playerImpl) Volume() float64 {
	p.m.Lock()
	v := p.volume
	p.m.Unlock()
	return v
}

// SetVolume sets the volume of this player.
// volume must be in between 0 and 1. SetVolume panics otherwise.
func (p *Player) SetVolume(volume float64) {
	p.p.SetVolume(volume)
}

func (p *playerImpl) SetVolume(volume float64) {
	// 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.m.Lock()
	p.volume = volume
	p.m.Unlock()
}