ebiten/audio/audio.go

572 lines
16 KiB
Go
Raw Permalink 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
//
2024-08-18 04:13:35 +02:00
// The stream format must be 16-bit little endian or 32-bit float little endian, and 2 channels. The format is as follows:
2022-08-03 13:48:02 +02:00
//
// [data] = [sample 1] [sample 2] [sample 3] ...
// [sample *] = [channel 1] ...
// [channel *] = [byte 1] [byte 2] ...
2016-04-10 10:07:58 +02:00
//
2024-08-18 04:13:35 +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.
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"
"reflect"
2016-03-28 17:06:37 +02:00
"runtime"
"sync"
2016-03-06 10:55:20 +01:00
"time"
"github.com/hajimehoshi/ebiten/v2/audio/internal/convert"
2023-10-06 06:49:42 +02:00
"github.com/hajimehoshi/ebiten/v2/internal/hook"
)
2016-03-12 20:48:13 +01:00
const (
channelCount = 2
bitDepthInBytesInt16 = 2
bitDepthInBytesFloat32 = 4
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 {
2021-08-21 12:52:11 +02:00
playerFactory *playerFactory
2017-12-23 16:23:57 +01:00
sampleRate int
err error
2018-10-13 15:41:37 +02:00
ready bool
2024-02-01 06:24:07 +01:00
playingPlayers 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.
//
2023-01-09 10:53:19 +01:00
// sampleRate specifies the number of samples that should be played during one second.
// Usual numbers are 44100 or 48000. One context has only one sample rate. You cannot play multiple audio
// sources with different sample rates at the same time.
2017-04-04 18:12:02 +02:00
//
// NewContext panics when an audio context is already created.
func NewContext(sampleRate int) *Context {
theContextLock.Lock()
defer theContextLock.Unlock()
2021-01-06 17:30:03 +01:00
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{
2024-02-01 06:24:07 +01:00
sampleRate: sampleRate,
playerFactory: newPlayerFactory(sampleRate),
playingPlayers: map[*playerImpl]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() error {
c.semaphore <- struct{}{}
if err := c.playerFactory.suspend(); err != nil {
return err
}
if err := c.onSuspend(); err != nil {
return err
}
return nil
})
h.OnResumeAudio(func() error {
<-c.semaphore
if err := c.playerFactory.resume(); err != nil {
return err
}
if err := c.onResume(); err != nil {
return err
}
return nil
})
2019-04-28 12:35:59 +02:00
h.AppendHookOnBeforeUpdate(func() error {
var err error
theContextLock.Lock()
if theContext != nil {
2021-10-22 08:29:00 +02:00
err = theContext.error()
}
theContextLock.Unlock()
if err != nil {
return err
}
// Initialize the context here in the case when there is no player and
// the program waits for IsReady() to be true (#969, #970, #2715).
ready, err := c.playerFactory.initContextIfNeeded()
if err != nil {
return err
}
if ready != nil {
go func() {
<-ready
c.setReady()
}()
}
if err := c.updatePlayers(); err != nil {
return err
}
return nil
})
2017-07-13 18:38:22 +02:00
return c
2019-04-27 15:30:09 +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
}
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()
}
2021-10-22 08:29:00 +02:00
func (c *Context) error() error {
c.m.Lock()
defer c.m.Unlock()
if c.err != nil {
return c.err
}
return c.playerFactory.error()
}
2019-04-28 13:31:20 +02:00
func (c *Context) setReady() {
c.m.Lock()
c.ready = true
c.m.Unlock()
}
2024-02-01 06:24:07 +01:00
func (c *Context) addPlayingPlayer(p *playerImpl) {
c.m.Lock()
defer c.m.Unlock()
2024-02-01 06:24:07 +01:00
c.playingPlayers[p] = struct{}{}
2024-09-11 17:20:49 +02:00
if !reflect.ValueOf(p.sourceIdent()).Comparable() {
return
}
// Check the source duplication
srcs := map[any]struct{}{}
2024-02-01 06:24:07 +01:00
for p := range c.playingPlayers {
if _, ok := srcs[p.sourceIdent()]; ok {
c.err = errors.New("audio: the same source must not be used by multiple Player objects")
return
}
srcs[p.sourceIdent()] = struct{}{}
}
}
2024-02-01 06:24:07 +01:00
func (c *Context) removePlayingPlayer(p *playerImpl) {
c.m.Lock()
2024-02-01 06:24:07 +01:00
delete(c.playingPlayers, p)
c.m.Unlock()
}
func (c *Context) onSuspend() error {
// A Context must not call playerImpl's functions with a lock, or this causes a deadlock (#2737).
// Copy the playerImpls and iterate them without a lock.
var players []*playerImpl
c.m.Lock()
players = make([]*playerImpl, 0, len(c.playingPlayers))
for p := range c.playingPlayers {
players = append(players, p)
}
c.m.Unlock()
for _, p := range players {
if err := p.Err(); err != nil {
return err
}
p.onContextSuspended()
}
return nil
}
func (c *Context) onResume() error {
// A Context must not call playerImpl's functions with a lock, or this causes a deadlock (#2737).
// Copy the playerImpls and iterate them without a lock.
var players []*playerImpl
c.m.Lock()
players = make([]*playerImpl, 0, len(c.playingPlayers))
for p := range c.playingPlayers {
players = append(players, p)
}
c.m.Unlock()
for _, p := range players {
if err := p.Err(); err != nil {
return err
}
p.onContextResumed()
}
return nil
}
func (c *Context) updatePlayers() error {
// A Context must not call playerImpl's functions with a lock, or this causes a deadlock (#2737).
// Copy the playerImpls and iterate them without a lock.
var players []*playerImpl
c.m.Lock()
2024-02-01 06:24:07 +01:00
players = make([]*playerImpl, 0, len(c.playingPlayers))
for p := range c.playingPlayers {
players = append(players, p)
}
c.m.Unlock()
var playersToRemove []*playerImpl
// Now reader players cannot call removePlayers from themselves in the current implementation.
// Underlying playering can be the pause state after fishing its playing,
2021-08-21 12:52:11 +02:00
// but there is no way to notify this to players so far.
// Instead, let's check the states proactively every frame.
for _, p := range players {
2021-08-21 12:52:11 +02:00
if err := p.Err(); err != nil {
return err
}
p.updatePosition()
2021-08-21 12:52:11 +02:00
if !p.IsPlaying() {
playersToRemove = append(playersToRemove, p)
}
}
c.m.Lock()
for _, p := range playersToRemove {
2024-02-01 06:24:07 +01:00
delete(c.playingPlayers, p)
}
c.m.Unlock()
return nil
}
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()
return c.ready
2018-10-13 15:41:37 +02: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
// 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 {
2021-12-17 08:01:24 +01:00
p *playerImpl
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
//
2022-07-23 11:17:05 +02:00
// src's format must be linear PCM (signed 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
//
// A Player doesn't close src even if src implements io.Closer.
// Closing the source is src owner's responsibility.
2024-07-21 14:40:33 +02:00
//
// For new code, NewPlayerF32 is preferrable to NewPlayer, since Ebitengine will treat only 32bit float audio internally in the future.
//
2024-07-21 14:45:53 +02:00
// A Player for 16bit integer must be used with 16bit integer version of audio APIs, like vorbis.DecodeWithoutResampling or audio.NewInfiniteLoop, not or vorbis.DecodeF32 or audio.NewInfiniteLoopF32.
func (c *Context) NewPlayer(src io.Reader) (*Player, error) {
_, seekable := src.(io.Seeker)
f32Src := convert.NewFloat32BytesReaderFromInt16BytesReader(src)
pi, err := c.playerFactory.newPlayer(c, f32Src, seekable, src, bitDepthInBytesFloat32)
2021-01-06 16:59:13 +01:00
if err != nil {
return nil, err
2016-04-15 17:52:07 +02:00
}
2021-01-06 16:59:13 +01:00
p := &Player{pi}
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
}
// NewPlayerF32 creates a new player with the given stream.
//
// src's format must be linear PCM (32bit float, 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.
//
2024-07-21 14:40:33 +02:00
// NewPlayerF32 tries to call Seek of src to get the current position.
// NewPlayerF32 returns error when the Seek returns error.
//
// A Player doesn't close src even if src implements io.Closer.
// Closing the source is src owner's responsibility.
2024-07-21 14:40:33 +02:00
//
// For new code, NewPlayerF32 is preferrable to NewPlayer, since Ebitengine will treat only 32bit float audio internally in the future.
//
2024-07-21 14:45:53 +02:00
// A Player for 32bit float must be used with 32bit float version of audio APIs, like vorbis.DecodeF32 or audio.NewInfiniteLoopF32, not vorbis.DecodeWithoutResampling or audio.NewInfiniteLoop.
func (c *Context) NewPlayerF32(src io.Reader) (*Player, error) {
_, seekable := src.(io.Seeker)
pi, err := c.playerFactory.newPlayer(c, src, seekable, src, bitDepthInBytesFloat32)
if err != nil {
return nil, err
}
p := &Player{pi}
runtime.SetFinalizer(p, (*Player).finalize)
return p, nil
}
// NewPlayer creates a new player with the given stream.
//
// Deprecated: as of v2.2. Use (*Context).NewPlayer instead.
func NewPlayer(context *Context, src io.Reader) (*Player, error) {
return context.NewPlayer(src)
}
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.
func (c *Context) NewPlayerFromBytes(src []byte) *Player {
p, err := c.NewPlayer(bytes.NewReader(src))
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
2016-06-26 19:22:44 +02:00
}
// NewPlayerF32FromBytes creates a new player with the given bytes.
//
// As opposed to NewPlayerF32, 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 NewPlayerF32.
func (c *Context) NewPlayerF32FromBytes(src []byte) *Player {
p, err := c.NewPlayerF32(bytes.NewReader(src))
if err != nil {
// Errors should never happen.
panic(fmt.Sprintf("audio: %v at NewPlayerFromBytesF32", err))
}
return p
}
// NewPlayerFromBytes creates a new player with the given bytes.
//
// Deprecated: as of v2.2. Use (*Context).NewPlayerFromBytes instead.
func NewPlayerFromBytes(context *Context, src []byte) *Player {
return context.NewPlayerFromBytes(src)
}
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
//
2020-10-07 16:43:33 +02:00
// When Close is called, the stream owned by the player is NOT closed,
// even if the stream implements io.Closer.
//
// Close returns error when the player is already closed.
2016-03-28 17:06:37 +02:00
func (p *Player) Close() error {
return p.p.Close()
}
2016-04-10 10:07:58 +02:00
// Play plays the stream.
func (p *Player) Play() {
p.p.Play()
2015-01-22 19:02:23 +01:00
}
2016-02-11 11:55:59 +01:00
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()
}
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()
}
// SetPosition sets the position with the given offset.
//
// The passed source to NewPlayer must be io.Seeker, or SetPosition panics.
2016-04-15 17:52:07 +02:00
//
// SetPosition returns error when seeking the source stream returns an error.
func (p *Player) SetPosition(offset time.Duration) error {
return p.p.SetPosition(offset)
}
// Seek seeks the position with the given offset.
//
// Deprecated: as of v2.6. Use SetPosition instead.
2016-03-06 10:55:20 +01:00
func (p *Player) Seek(offset time.Duration) error {
return p.SetPosition(offset)
}
2016-04-10 10:07:58 +02:00
// Pause pauses the playing.
func (p *Player) Pause() {
p.p.Pause()
2016-02-11 11:55:59 +01:00
}
2016-03-06 10:55:20 +01:00
// Position returns the current position in time.
//
// As long as the player continues to play, Position's returning value is increased monotonically,
// even though the source stream loops and its position goes back.
func (p *Player) Position() time.Duration {
return p.p.Position()
}
// Current returns the current position in time.
//
// Deprecated: as of v2.6. Use Position instead.
2016-03-06 10:55:20 +01:00
func (p *Player) Current() time.Duration {
return p.Position()
}
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()
}
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)
}
// SetBufferSize adjusts the buffer size of the player.
// If 0 is specified, the default buffer size is used.
// A small buffer size is useful if you want to play a real-time PCM for example.
// Note that the audio quality might be affected if you modify the buffer size.
func (p *Player) SetBufferSize(bufferSize time.Duration) {
p.p.SetBufferSize(bufferSize)
}
2023-10-06 06:49:42 +02:00
type hooker interface {
OnSuspendAudio(f func() error)
OnResumeAudio(f func() error)
AppendHookOnBeforeUpdate(f func() error)
}
2023-10-06 06:49:42 +02:00
var hookerForTesting hooker
2023-10-06 06:49:42 +02:00
func getHook() hooker {
if hookerForTesting != nil {
return hookerForTesting
}
2023-10-06 06:49:42 +02:00
return &hookerImpl{}
}
2023-10-06 06:49:42 +02:00
type hookerImpl struct{}
2023-10-06 06:49:42 +02:00
func (h *hookerImpl) OnSuspendAudio(f func() error) {
hook.OnSuspendAudio(f)
}
2023-10-06 06:49:42 +02:00
func (h *hookerImpl) OnResumeAudio(f func() error) {
hook.OnResumeAudio(f)
}
2023-10-06 06:49:42 +02:00
func (h *hookerImpl) AppendHookOnBeforeUpdate(f func() error) {
hook.AppendHookOnBeforeUpdate(f)
}
// Resample converts the sample rate of the given singed 16bit integer, little-endian, 2 channels (stereo) stream.
// size is the length of the source stream in bytes.
// from is the original sample rate.
// to is the target sample rate.
//
// If the original sample rate equals to the new one, Resample returns source as it is.
func Resample(source io.ReadSeeker, size int64, from, to int) io.ReadSeeker {
if from == to {
return source
}
return convert.NewResampling(source, size, from, to, bitDepthInBytesInt16)
}
// ResampleF32 converts the sample rate of the given 32bit float, little-endian, 2 channels (stereo) stream.
// size is the length of the source stream in bytes.
// from is the original sample rate.
// to is the target sample rate.
//
// If the original sample rate equals to the new one, Resample returns source as it is.
func ResampleF32(source io.ReadSeeker, size int64, from, to int) io.ReadSeeker {
if from == to {
return source
}
return convert.NewResampling(source, size, from, to, bitDepthInBytesFloat32)
}