ebiten/audio/audio.go

606 lines
14 KiB
Go
Raw Normal View History

2015-01-10 17:23:43 +01:00
// 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.
2017-10-01 10:24:30 +02:00
// Package audio provides audio players.
2016-04-10 10:07:58 +02:00
//
2017-10-01 10:24:30 +02:00
// 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] ...
2016-04-10 10:07:58 +02:00
//
2017-10-01 10:24:30 +02:00
// 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,
2017-01-15 10:02:21 +01:00
// and you don't have to care about it as long as you use those decoders.
2016-04-10 10:07:58 +02:00
//
2017-10-01 10:24:30 +02:00
// An audio context can generate 'players' (audio.Player objects),
2016-04-10 10:07:58 +02:00
// 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.
2017-07-13 19:26:41 +02:00
//
2017-10-01 10:24:30 +02:00
// For the simplest example to play sound, see wav package in the examples.
2015-01-23 15:04:56 +01:00
package audio
2015-01-10 17:23:43 +01:00
import (
2016-06-26 19:22:44 +02:00
"bytes"
"errors"
"fmt"
2016-02-10 18:04:23 +01:00
"io"
2016-03-28 17:06:37 +02:00
"runtime"
"sync"
2016-03-06 10:55:20 +01:00
"time"
)
2016-03-12 20:48:13 +01:00
const (
channelNum = 2
bytesPerSample = 2 * channelNum
2015-01-10 17:23:43 +01:00
)
2017-10-01 10:24:30 +02:00
// A Context represents a current state of audio.
2016-04-10 10:07:58 +02:00
//
2017-10-01 10:24:30 +02:00
// At most one Context object can exist in one process.
2016-09-26 16:08:34 +02:00
// This means only one constant sample rate is valid in your one application.
//
2017-11-30 17:38:47 +01:00
// For a typical usage example, see examples/wav/main.go.
2016-03-02 16:48:59 +01:00
type Context struct {
c context
// inited represents whether the audio device is initialized and available or not.
// On Android, audio loop cannot be started unless JVM is accessible. After updating one frame, JVM should exist.
inited chan struct{}
initedOnce sync.Once
2017-12-23 16:23:57 +01:00
sampleRate int
err error
2018-10-13 15:41:37 +02:00
ready bool
players map[*playerImpl]struct{}
m sync.Mutex
semaphore chan struct{}
2016-03-02 16:48:59 +01:00
}
var (
theContext *Context
theContextLock sync.Mutex
)
2017-09-25 17:38:50 +02:00
// NewContext creates a new audio context with the given sample rate.
//
2017-10-01 10:24:30 +02:00
// The sample rate is also used for decoding MP3 with audio/mp3 package
// or other formats as the target sample rate.
2017-09-25 17:38:50 +02:00
//
// sampleRate should be 44100 or 48000.
// Other values might not work.
// For example, 22050 causes error on Safari when decoding MP3.
2017-04-04 18:12:02 +02:00
//
// 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 {
2017-04-04 18:12:02 +02:00
panic("audio: context is already created")
}
2016-04-15 17:52:07 +02:00
c := &Context{
sampleRate: sampleRate,
2019-04-27 15:30:09 +02:00
c: newContext(sampleRate),
players: map[*playerImpl]struct{}{},
inited: make(chan struct{}),
semaphore: make(chan struct{}, 1),
2016-04-15 17:52:07 +02:00
}
theContext = c
2019-04-28 12:35:59 +02:00
h := getHook()
h.OnSuspendAudio(func() {
c.semaphore <- struct{}{}
})
2019-04-28 12:35:59 +02:00
h.OnResumeAudio(func() {
<-c.semaphore
})
2019-04-28 12:35:59 +02:00
h.AppendHookOnBeforeUpdate(func() error {
c.initedOnce.Do(func() {
close(c.inited)
})
var err error
theContextLock.Lock()
if theContext != nil {
theContext.m.Lock()
err = theContext.err
theContext.m.Unlock()
}
theContextLock.Unlock()
return err
})
2017-07-13 18:38:22 +02:00
2019-04-27 15:30:09 +02:00
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) hasError() bool {
c.m.Lock()
r := c.err != nil
c.m.Unlock()
return r
}
2019-04-28 13:31:20 +02:00
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) addPlayer(p *playerImpl) {
c.m.Lock()
defer c.m.Unlock()
c.players[p] = struct{}{}
// Check the source duplication
srcs := map[io.ReadCloser]struct{}{}
for p := range c.players {
if _, ok := srcs[p.src]; ok {
c.err = errors.New("audio: a same source is used by multiple Player")
return
}
srcs[p.src] = struct{}{}
}
}
func (c *Context) removePlayer(p *playerImpl) {
c.m.Lock()
delete(c.players, p)
c.m.Unlock()
}
2018-10-13 15:41:37 +02:00
// 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()
defer c.m.Unlock()
2018-10-13 15:41:37 +02:00
r := c.ready
if r {
return r
}
if len(c.players) != 0 {
return r
}
// Create another goroutine since (*Player).Play can lock the context's mutex.
go func() {
// The audio context is never ready unless there is a player. This is
// problematic when a user tries to play audio after the context is ready.
// Play a dummy player to avoid the blocking (#969).
// Use a long enough buffer so that writing doesn't finish immediately (#970).
p, _ := NewPlayerFromBytes(c, make([]byte, bufferSize()*2))
p.Play()
}()
2018-10-13 15:41:37 +02:00
return r
}
2017-11-30 16:26:28 +01:00
// Update is deprecated as of 1.6.0-alpha.
2017-07-13 18:45:36 +02:00
//
2017-11-30 16:26:28 +01:00
// 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.
2017-11-30 16:26:28 +01:00
// The internal audio error is returned at ebiten.Run instead.
func (c *Context) Update() error {
return nil
2016-03-10 16:01:00 +01:00
}
// SampleRate returns the sample rate.
func (c *Context) SampleRate() int {
2016-04-15 17:52:07 +02:00
return c.sampleRate
}
2016-04-04 19:24:54 +02:00
// ReadSeekCloser is an io.ReadSeeker and io.Closer.
2016-03-28 17:06:37 +02:00
type ReadSeekCloser interface {
io.ReadSeeker
io.Closer
}
type bytesReadSeekCloser struct {
reader *bytes.Reader
}
2017-12-22 18:05:49 +01:00
func (b *bytesReadSeekCloser) Read(buf []byte) (int, error) {
return b.reader.Read(buf)
2017-01-15 18:21:21 +01:00
}
func (b *bytesReadSeekCloser) Seek(offset int64, whence int) (int64, error) {
return b.reader.Seek(offset, whence)
}
func (b *bytesReadSeekCloser) Close() error {
b.reader = nil
2017-01-15 18:21:21 +01:00
return nil
}
// BytesReadSeekCloser creates ReadSeekCloser from bytes.
2017-12-22 18:05:49 +01:00
func BytesReadSeekCloser(b []byte) ReadSeekCloser {
2017-06-03 18:03:01 +02:00
return &bytesReadSeekCloser{reader: bytes.NewReader(b)}
2017-01-15 18:21:21 +01:00
}
2016-04-04 19:24:54 +02:00
// Player is an audio player which has one stream.
2018-12-18 15:07:19 +01:00
//
// 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.
2016-02-10 18:18:39 +01:00
type Player struct {
p *playerImpl
}
type playerImpl struct {
context *Context
src io.ReadCloser
sampleRate int
2019-04-28 18:01:17 +02:00
playing bool
closedExplicitly bool
isLoopActive bool
2017-12-22 18:05:49 +01:00
buf []byte
pos int64
volume float64
m sync.Mutex
2016-02-10 18:18:39 +01:00
}
2016-04-10 10:07:58 +02:00
// NewPlayer creates a new player with the given stream.
2015-01-24 07:48:48 +01:00
//
2016-04-10 10:07:58 +02:00
// src's format must be linear PCM (16bits little endian, 2 channel stereo)
2016-02-07 16:51:25 +01:00
// without a header (e.g. RIFF header).
2016-04-10 10:07:58 +02:00
// The sample rate must be same as that of the audio context.
2016-04-15 17:52:07 +02:00
//
// The player is seekable when src is io.Seeker.
// Attempt to seek the player that is not io.Seeker causes panic.
//
2017-10-01 10:24:30 +02:00
// Note that the given src can't be shared with other Player objects.
//
2017-10-01 10:24:30 +02:00
// NewPlayer tries to call Seek of src to get the current position.
// NewPlayer returns error when the Seek returns error.
2019-03-31 18:59:10 +02:00
//
// NewPlayer takes the ownership of src. Player's Close calls src's Close.
func NewPlayer(context *Context, src io.ReadCloser) (*Player, error) {
2016-04-15 17:52:07 +02:00
p := &Player{
&playerImpl{
context: context,
src: src,
sampleRate: context.sampleRate,
volume: 1,
},
2016-04-15 17:52:07 +02:00
}
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
2016-04-15 17:52:07 +02:00
}
runtime.SetFinalizer(p, (*Player).finalize)
2017-12-23 09:24:51 +01:00
2016-04-15 17:52:07 +02:00
return p, nil
2016-03-03 03:57:25 +01:00
}
2016-06-26 19:22:44 +02:00
// 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.
2017-12-22 18:05:49 +01:00
func NewPlayerFromBytes(context *Context, src []byte) (*Player, error) {
b := BytesReadSeekCloser(src)
p, err := NewPlayer(context, b)
if err != nil {
// Errors should never happen.
2019-02-07 09:19:24 +01:00
panic(fmt.Sprintf("audio: %v at NewPlayerFromBytes", err))
}
return p, nil
2016-06-26 19:22:44 +02:00
}
func (p *Player) finalize() {
runtime.SetFinalizer(p, nil)
if !p.IsPlaying() {
p.Close()
}
}
2017-10-01 10:24:30 +02:00
// Close closes the stream.
2016-04-15 17:52:07 +02:00
//
2016-06-27 19:50:13 +02:00
// When closing, the stream owned by the player will also be closed by calling its Close.
2017-10-01 10:24:30 +02:00
// This means that the source stream passed via NewPlayer will also be closed.
//
2017-04-04 18:12:02 +02:00
// Close returns error when closing the source returns error.
2016-03-28 17:06:37 +02:00
func (p *Player) Close() error {
2016-04-15 17:52:07 +02:00
runtime.SetFinalizer(p, nil)
return p.p.Close()
}
func (p *playerImpl) Close() error {
p.m.Lock()
defer p.m.Unlock()
2019-04-28 18:01:17 +02:00
p.playing = false
if p.closedExplicitly {
return fmt.Errorf("audio: the player is already closed")
}
p.closedExplicitly = true
// src.Close is called only when Player's Close is called.
2019-05-01 21:10:33 +02:00
// TODO: Is it ok not to call src.Close when GCed?
if err := p.src.Close(); err != nil {
return err
}
return nil
2016-03-06 14:03:11 +01:00
}
2016-04-10 10:07:58 +02:00
// Play plays the stream.
2016-04-15 17:52:07 +02:00
//
2017-04-04 18:12:02 +02:00
// Play always returns nil.
2016-02-10 18:18:39 +01:00
func (p *Player) Play() error {
p.p.Play()
2016-03-03 03:57:25 +01:00
return nil
2015-01-22 19:02:23 +01:00
}
2016-02-11 11:55:59 +01:00
func (p *playerImpl) Play() {
2019-04-28 18:01:17 +02:00
p.m.Lock()
defer p.m.Unlock()
if p.closedExplicitly {
p.context.setError(fmt.Errorf("audio: the player is already closed"))
return
}
2019-04-28 18:01:17 +02:00
p.playing = true
if p.isLoopActive {
return
}
// Set p.isLoopActive to true here, not in the loop. This prevents duplicated active loops.
p.isLoopActive = true
p.context.addPlayer(p)
go p.loop()
return
}
func (p *playerImpl) loop() {
<-p.context.inited
w := p.context.c.NewPlayer()
wclosed := make(chan struct{})
defer func() {
<-wclosed
w.Close()
}()
defer func() {
p.m.Lock()
p.playing = false
p.context.removePlayer(p)
p.isLoopActive = false
p.m.Unlock()
}()
ch := make(chan []byte)
defer close(ch)
2017-12-23 09:24:51 +01:00
go func() {
for buf := range ch {
if _, err := w.Write(buf); err != nil {
p.context.setError(err)
2017-12-23 09:05:14 +01:00
break
}
p.context.setReady()
}
close(wclosed)
}()
2017-12-23 09:24:51 +01:00
for {
buf, ok := p.read()
if !ok {
return
}
ch <- buf
}
}
2017-12-23 09:24:51 +01:00
func (p *playerImpl) read() ([]byte, bool) {
p.m.Lock()
defer p.m.Unlock()
2017-12-23 09:24:51 +01:00
if p.context.hasError() {
return nil, false
}
if p.closedExplicitly {
return nil, false
}
// playing can be false when pausing.
if !p.playing {
return nil, false
}
const bufSize = 2048
2017-12-23 09:24:51 +01:00
p.context.semaphore <- struct{}{}
defer func() {
<-p.context.semaphore
}()
2019-05-01 20:19:17 +02:00
newBuf := make([]byte, bufSize-len(p.buf))
n, err := p.src.Read(newBuf)
if err != nil {
if err != io.EOF {
p.context.setError(err)
return nil, false
}
if n == 0 {
return nil, false
}
}
2019-05-01 20:19:17 +02:00
buf := append(p.buf, newBuf[:n]...)
2019-05-01 20:19:17 +02:00
n2 := len(buf) - len(buf)%bytesPerSample
buf, p.buf = buf[:n2], buf[n2:]
for i := 0; i < len(buf)/2; i++ {
v16 := int16(buf[2*i]) | (int16(buf[2*i+1]) << 8)
v16 = int16(float64(v16) * p.volume)
buf[2*i] = byte(v16)
buf[2*i+1] = byte(v16 >> 8)
}
2019-05-01 20:19:17 +02:00
p.pos += int64(len(buf))
2017-12-22 18:05:49 +01:00
return buf, true
}
2016-04-10 10:07:58 +02:00
// IsPlaying returns boolean indicating whether the player is playing.
2016-03-06 10:55:20 +01:00
func (p *Player) IsPlaying() bool {
return p.p.IsPlaying()
}
func (p *playerImpl) IsPlaying() bool {
2019-04-28 18:01:17 +02:00
p.m.Lock()
r := p.playing
p.m.Unlock()
return r
2016-03-06 10:55:20 +01:00
}
2016-04-10 10:07:58 +02:00
// Rewind rewinds the current position to the start.
2016-04-15 17:52:07 +02:00
//
// The passed source to NewPlayer must be io.Seeker, or Rewind panics.
//
2017-10-01 10:24:30 +02:00
// Rewind returns error when seeking the source stream returns error.
2016-03-06 10:55:20 +01:00
func (p *Player) Rewind() error {
return p.p.Rewind()
}
func (p *playerImpl) Rewind() error {
if _, ok := p.src.(io.Seeker); !ok {
2018-03-21 16:36:38 +01:00
panic("audio: player to be rewound must be io.Seeker")
}
2016-03-06 10:55:20 +01:00
return p.Seek(0)
}
2016-04-10 10:07:58 +02:00
// Seek seeks the position with the given offset.
2016-04-15 17:52:07 +02:00
//
// The passed source to NewPlayer must be io.Seeker, or Seek panics.
//
2017-10-01 10:24:30 +02:00
// Seek returns error when seeking the source stream returns error.
2016-03-06 10:55:20 +01:00
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")
}
p.m.Lock()
defer p.m.Unlock()
o := int64(offset) * bytesPerSample * int64(p.sampleRate) / int64(time.Second)
o = o - (o % bytesPerSample)
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
return nil
}
2016-04-10 10:07:58 +02:00
// Pause pauses the playing.
2016-04-15 17:52:07 +02:00
//
2017-04-04 18:12:02 +02:00
// Pause always returns nil.
2016-03-04 17:01:57 +01:00
func (p *Player) Pause() error {
p.p.Pause()
2016-03-03 03:57:25 +01:00
return nil
2016-02-11 11:55:59 +01:00
}
2016-03-06 10:55:20 +01:00
func (p *playerImpl) Pause() {
2019-04-28 18:01:17 +02:00
p.m.Lock()
p.playing = false
p.m.Unlock()
}
2019-05-01 19:11:35 +02:00
// Current returns the current position in time.
2016-03-06 10:55:20 +01:00
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()
2017-12-23 10:39:14 +01:00
return time.Duration(sample) * time.Second / time.Duration(p.sampleRate)
2016-03-06 10:55:20 +01:00
}
2016-04-10 10:07:58 +02:00
// Volume returns the current volume of this player [0-1].
2016-03-28 04:06:17 +02:00
func (p *Player) Volume() float64 {
return p.p.Volume()
}
func (p *playerImpl) Volume() float64 {
p.m.Lock()
v := p.volume
p.m.Unlock()
2017-06-03 20:14:48 +02:00
return v
2016-03-28 04:06:17 +02:00
}
2016-04-10 10:07:58 +02:00
// SetVolume sets the volume of this player.
// volume must be in between 0 and 1. SetVolume panics otherwise.
2016-03-28 04:06:17 +02:00
func (p *Player) SetVolume(volume float64) {
p.p.SetVolume(volume)
}
func (p *playerImpl) SetVolume(volume float64) {
2016-04-02 19:46:18 +02:00
// The condition must be true when volume is NaN.
if !(0 <= volume && volume <= 1) {
panic("audio: volume must be in between 0 and 1")
2016-03-28 04:06:17 +02:00
}
2017-12-23 10:39:14 +01:00
p.m.Lock()
p.volume = volume
p.m.Unlock()
2016-03-28 04:06:17 +02:00
}