ebiten/audio/audio.go

624 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-12-23 13:14:08 +01:00
// Ebiten's game progress tries to synchronizes with audio progress, but
// delay can happen if, e.g., decoding an audio source takes long.
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
"github.com/hajimehoshi/oto"
2017-07-13 17:28:28 +02:00
2017-11-30 16:26:28 +01:00
"github.com/hajimehoshi/ebiten/internal/audiobinding"
2017-07-13 17:28:28 +02:00
"github.com/hajimehoshi/ebiten/internal/clock"
"github.com/hajimehoshi/ebiten/internal/web"
2015-01-10 17:23:43 +01:00
)
2016-04-15 17:52:07 +02:00
type players struct {
2017-06-04 09:46:02 +02:00
players map[*Player]struct{}
2016-04-04 19:24:54 +02:00
sync.RWMutex
2016-03-03 03:57:25 +01:00
}
2016-03-12 19:33:02 +01:00
const (
channelNum = 2
bytesPerSample = 2
2016-03-19 17:40:10 +01:00
// TODO: This assumes that channelNum is a power of 2.
mask = ^(channelNum*bytesPerSample - 1)
2016-03-12 19:33:02 +01:00
)
2017-12-22 18:05:49 +01:00
func (p *players) Read(b []byte) (int, error) {
2016-04-15 17:52:07 +02:00
p.Lock()
defer p.Unlock()
2016-03-03 03:57:25 +01:00
2017-12-22 20:01:18 +01:00
if len(p.players) == 0 {
l := len(b)
2016-03-15 19:02:54 +01:00
l &= mask
2017-12-22 18:05:49 +01:00
copy(b, make([]byte, l))
2016-03-10 16:01:00 +01:00
return l, nil
2016-03-03 03:57:25 +01:00
}
l := len(b)
2016-03-15 19:02:54 +01:00
l &= mask
2016-03-06 14:03:11 +01:00
b16s := [][]int16{}
2017-12-22 20:01:18 +01:00
for player := range p.players {
2017-12-23 09:24:51 +01:00
buf, err := player.bufferToInt16(l)
if err != nil {
return 0, err
}
b16s = append(b16s, buf)
2016-03-03 03:57:25 +01:00
}
for i := 0; i < l/2; i++ {
2016-03-03 04:22:10 +01:00
x := 0
2016-03-06 14:03:11 +01:00
for _, b16 := range b16s {
x += int(b16[i])
2016-03-03 04:22:10 +01:00
}
if x > (1<<15)-1 {
x = (1 << 15) - 1
}
if x < -(1 << 15) {
x = -(1 << 15)
2016-03-03 03:57:25 +01:00
}
b[2*i] = byte(x)
b[2*i+1] = byte(x >> 8)
}
2017-12-22 20:01:18 +01:00
closed := []*Player{}
for player := range p.players {
2017-12-22 18:05:49 +01:00
if player.eof() {
2017-12-22 20:01:18 +01:00
closed = append(closed, player)
2017-12-22 18:05:49 +01:00
}
2016-03-03 03:57:25 +01:00
}
2017-12-22 20:01:18 +01:00
for _, player := range closed {
delete(p.players, player)
}
return l, nil
2016-03-03 03:57:25 +01:00
}
2016-04-15 17:52:07 +02:00
func (p *players) addPlayer(player *Player) {
p.Lock()
p.players[player] = struct{}{}
p.Unlock()
}
2016-04-15 17:52:07 +02:00
func (p *players) removePlayer(player *Player) {
p.Lock()
delete(p.players, player)
p.Unlock()
}
2016-04-15 17:52:07 +02:00
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
}
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 {
2017-12-23 16:23:57 +01:00
players *players
initCh chan struct{}
initedCh chan struct{}
pingCount int
sampleRate int
m sync.Mutex
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,
2016-04-15 17:52:07 +02:00
}
theContext = c
2016-04-15 17:52:07 +02:00
c.players = &players{
2017-06-04 09:46:02 +02:00
players: map[*Player]struct{}{},
2016-03-10 16:01:00 +01:00
}
2017-08-17 04:15:04 +02:00
go c.loop()
return c, nil
}
2017-10-01 10:24:30 +02:00
// CurrentContext returns the current context or nil if there is no context.
func CurrentContext() *Context {
theContextLock.Lock()
c := theContext
theContextLock.Unlock()
return c
2016-03-02 16:48:59 +01:00
}
2017-07-13 18:38:22 +02:00
func (c *Context) ping() {
if c.initCh != nil {
close(c.initCh)
c.initCh = nil
}
2017-08-17 04:05:59 +02:00
<-c.initedCh
c.m.Lock()
c.pingCount = 5
c.m.Unlock()
}
2017-08-17 04:15:04 +02:00
func (c *Context) loop() {
c.initCh = make(chan struct{})
c.initedCh = make(chan struct{})
// Copy the channel since c.initCh can be set as nil after clock.RegisterPing.
initCh := c.initCh
clock.RegisterPing(c.ping)
2017-07-13 18:38:22 +02:00
// Initialize oto.Player lazily to enable calling NewContext in an 'init' function.
// Accessing oto.Player functions requires the environment to be already initialized,
2016-05-26 16:33:12 +02:00
// 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.
2017-08-17 04:05:59 +02:00
<-initCh
p, err := oto.NewPlayer(c.sampleRate, channelNum, bytesPerSample, bufferSize())
if err != nil {
2017-11-30 16:26:28 +01:00
audiobinding.SetError(err)
return
}
defer p.Close()
close(c.initedCh)
2017-12-23 16:23:57 +01:00
bytesPerFrame := c.sampleRate * bytesPerSample * channelNum / clock.FPS
written := int64(0)
prevWritten := int64(0)
for {
c.m.Lock()
if c.pingCount == 0 {
c.m.Unlock()
time.Sleep(10 * time.Millisecond)
continue
}
c.pingCount--
c.m.Unlock()
2017-12-23 16:23:57 +01:00
const n = 4096
2017-12-30 13:18:34 +01:00
if _, err := io.CopyN(p, c.players, n); err != nil {
2017-11-30 16:26:28 +01:00
audiobinding.SetError(err)
return
}
2017-12-23 16:23:57 +01:00
written += int64(n)
fs := written/int64(bytesPerFrame) - prevWritten/int64(bytesPerFrame)
for fs > 0 {
clock.ProceedPrimaryTimer()
fs--
}
prevWritten = written
}
}
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.
2017-12-02 08:26:20 +01:00
// You don't have to call this function 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.
2016-02-10 18:18:39 +01:00
type Player struct {
2016-04-15 17:52:07 +02:00
players *players
src ReadSeekCloser
2017-12-22 18:05:49 +01:00
srcEOF bool
2016-04-15 17:52:07 +02:00
sampleRate int
2017-12-22 18:05:49 +01:00
buf []byte
pos int64
volume float64
closeCh chan struct{}
closedCh chan struct{}
readLoopEndedCh chan struct{}
seekCh chan seekArgs
seekedCh chan error
proceedCh chan []int16
proceededCh chan proceededValues
2017-12-23 10:51:45 +01:00
syncCh chan func()
2016-02-10 18:18:39 +01:00
}
2017-12-23 09:24:51 +01:00
type seekArgs struct {
offset int64
whence int
}
type proceededValues struct {
buf []int16
err error
}
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
//
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.
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")
}
2016-04-15 17:52:07 +02:00
p := &Player{
players: context.players,
src: src,
sampleRate: context.sampleRate,
buf: []byte{},
volume: 1,
closeCh: make(chan struct{}),
closedCh: make(chan struct{}),
readLoopEndedCh: make(chan struct{}),
seekCh: make(chan seekArgs),
seekedCh: make(chan error),
proceedCh: make(chan []int16),
proceededCh: make(chan proceededValues),
2017-12-23 10:51:45 +01:00
syncCh: make(chan func()),
2016-04-15 17:52:07 +02:00
}
// Get the current position of the source.
2016-11-28 19:36:16 +01:00
pos, err := p.src.Seek(0, io.SeekCurrent)
2016-04-15 17:52:07 +02:00
if err != nil {
return nil, err
}
p.pos = pos
runtime.SetFinalizer(p, (*Player).Close)
2017-12-23 09:24:51 +01:00
go func() {
p.readLoop()
}()
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.
panic(err)
}
return p, nil
2016-06-26 19:22:44 +02:00
}
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)
2017-12-22 18:05:49 +01:00
p.players.removePlayer(p)
select {
case p.closeCh <- struct{}{}:
<-p.closedCh
return nil
case <-p.readLoopEndedCh:
return fmt.Errorf("audio: the player is already closed")
}
2016-03-06 14:03:11 +01:00
}
2017-12-23 09:24:51 +01:00
func (p *Player) bufferToInt16(lengthInBytes int) ([]int16, error) {
select {
case p.proceedCh <- make([]int16, lengthInBytes/2):
r := <-p.proceededCh
return r.buf, r.err
case <-p.readLoopEndedCh:
return nil, fmt.Errorf("audio: the player is already closed")
}
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 {
2016-04-15 17:52:07 +02:00
p.players.addPlayer(p)
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
2017-12-22 20:12:12 +01:00
func (p *Player) readLoop() {
defer func() {
// Note: the error is ignored
p.src.Close()
2017-12-23 10:51:45 +01:00
// Receiving from a closed channel returns quickly
// i.e. `case <-p.readLoopEndedCh:` can check if this loops is ended.
close(p.readLoopEndedCh)
}()
2017-12-23 09:05:14 +01:00
t := time.After(0)
2017-12-23 09:24:51 +01:00
var readErr error
2017-12-22 18:05:49 +01:00
for {
select {
case <-p.closeCh:
p.closedCh <- struct{}{}
2017-12-22 20:12:12 +01:00
return
2017-12-23 09:24:51 +01:00
case s := <-p.seekCh:
pos, err := p.src.Seek(s.offset, s.whence)
p.buf = nil
p.pos = pos
p.srcEOF = false
p.seekedCh <- err
t = time.After(time.Millisecond)
break
2017-12-22 18:05:49 +01:00
case <-t:
2017-12-23 14:52:01 +01:00
// If the buffer has 1 second, that's enough.
2017-12-23 16:23:57 +01:00
if len(p.buf) >= p.sampleRate*bytesPerSample*channelNum {
2017-12-23 11:59:52 +01:00
t = time.After(100 * time.Millisecond)
2017-12-23 09:05:14 +01:00
break
}
2017-12-23 09:24:51 +01:00
// Try to read the buffer for 1/60[s].
2017-12-23 19:41:36 +01:00
s := 60
if web.IsAndroidChrome() {
s = 10
} else if web.IsBrowser() {
s = 20
}
l := p.sampleRate * bytesPerSample * channelNum / s
2017-12-23 11:59:52 +01:00
l &= mask
buf := make([]byte, l)
2017-12-23 09:05:14 +01:00
n, err := p.src.Read(buf)
2017-12-23 09:24:51 +01:00
2017-12-23 09:05:14 +01:00
p.buf = append(p.buf, buf[:n]...)
if err == io.EOF {
p.srcEOF = true
}
if p.srcEOF && len(p.buf) == 0 {
t = nil
2017-12-23 09:24:51 +01:00
break
2017-12-23 09:05:14 +01:00
}
if err != nil && err != io.EOF {
2017-12-23 09:24:51 +01:00
readErr = err
2017-12-23 09:05:14 +01:00
t = nil
2017-12-23 09:24:51 +01:00
break
2017-12-22 18:05:49 +01:00
}
2017-12-23 19:41:36 +01:00
if web.IsBrowser() {
t = time.After(10 * time.Millisecond)
} else {
t = time.After(time.Millisecond)
}
2017-12-23 09:24:51 +01:00
case buf := <-p.proceedCh:
if readErr != nil {
p.proceededCh <- proceededValues{buf, readErr}
return
}
lengthInBytes := len(buf) * 2
l := lengthInBytes
if len(p.buf) < lengthInBytes && !p.srcEOF {
2017-12-23 09:24:51 +01:00
p.proceededCh <- proceededValues{buf, nil}
break
}
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.proceededCh <- proceededValues{buf, nil}
2017-12-23 10:51:45 +01:00
case f := <-p.syncCh:
f()
2017-12-22 18:05:49 +01:00
}
}
}
2017-12-23 10:51:45 +01:00
func (p *Player) sync(f func()) bool {
ch := make(chan struct{})
ff := func() {
f()
close(ch)
}
select {
case p.syncCh <- ff:
<-ch
return true
case <-p.readLoopEndedCh:
return false
}
}
2017-12-22 18:05:49 +01:00
func (p *Player) eof() bool {
2017-12-23 10:51:45 +01:00
r := false
p.sync(func() {
r = p.srcEOF && len(p.buf) == 0
})
2017-12-22 18:05:49 +01:00
return r
}
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 {
2016-04-15 17:52:07 +02:00
return p.players.hasPlayer(p)
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
//
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.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
//
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 {
2016-04-15 17:52:07 +02:00
o := int64(offset) * bytesPerSample * channelNum * int64(p.sampleRate) / int64(time.Second)
o &= mask
select {
case p.seekCh <- seekArgs{o, io.SeekStart}:
return <-p.seekedCh
case <-p.readLoopEndedCh:
return fmt.Errorf("audio: the player is already closed")
}
}
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 {
2016-04-15 17:52:07 +02:00
p.players.removePlayer(p)
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
2016-04-10 10:07:58 +02:00
// Current returns the current position.
2016-03-06 10:55:20 +01:00
func (p *Player) Current() time.Duration {
2017-12-23 10:51:45 +01:00
sample := int64(0)
p.sync(func() {
sample = p.pos / bytesPerSample / channelNum
})
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 {
2017-12-23 10:51:45 +01:00
v := 0.0
p.sync(func() {
v = p.volume
})
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.
2016-04-03 19:16:26 +02:00
// volume must be in between 0 and 1. This function panics otherwise.
2016-03-28 04:06:17 +02:00
func (p *Player) 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
2017-12-23 10:51:45 +01:00
p.sync(func() {
p.volume = volume
})
2016-03-28 04:06:17 +02:00
}