audio

package
v2.8.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 5, 2024 License: Apache-2.0 Imports: 12 Imported by: 293

Documentation

Overview

Package audio provides audio players.

The stream format must be 16-bit little endian or 32-bit float 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.

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.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Resample added in v2.4.0

func Resample(source io.ReadSeeker, size int64, from, to int) io.ReadSeeker

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 ResampleF32 added in v2.8.0

func ResampleF32(source io.ReadSeeker, size int64, from, to int) io.ReadSeeker

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.

Types

type Context

type Context struct {
	// contains filtered or unexported fields
}

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.

func CurrentContext

func CurrentContext() *Context

CurrentContext returns the current context or nil if there is no context.

func NewContext

func NewContext(sampleRate int) *Context

NewContext creates a new audio context with the given sample rate.

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.

NewContext panics when an audio context is already created.

func (*Context) IsReady

func (c *Context) IsReady() bool

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 (*Context) NewPlayer added in v2.2.0

func (c *Context) NewPlayer(src io.Reader) (*Player, error)

NewPlayer creates a new player with the given stream.

src's format must be linear PCM (signed 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.

A Player doesn't close src even if src implements io.Closer. Closing the source is src owner's responsibility.

For new code, NewPlayerF32 is preferrable to NewPlayer, since Ebitengine will treat only 32bit float audio internally in the future.

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 (*Context) NewPlayerF32 added in v2.8.0

func (c *Context) NewPlayerF32(src io.Reader) (*Player, error)

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.

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.

For new code, NewPlayerF32 is preferrable to NewPlayer, since Ebitengine will treat only 32bit float audio internally in the future.

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 (*Context) NewPlayerF32FromBytes added in v2.8.0

func (c *Context) NewPlayerF32FromBytes(src []byte) *Player

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 (*Context) NewPlayerFromBytes added in v2.2.0

func (c *Context) NewPlayerFromBytes(src []byte) *Player

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 (*Context) SampleRate

func (c *Context) SampleRate() int

SampleRate returns the sample rate.

type InfiniteLoop

type InfiniteLoop struct {
	// contains filtered or unexported fields
}

InfiniteLoop represents a looped stream which never ends.

func NewInfiniteLoop

func NewInfiniteLoop(src io.ReadSeeker, length int64) *InfiniteLoop

NewInfiniteLoop creates a new infinite loop stream with a source stream and length in bytes.

src is a signed 16bit integer little endian stream, 2 channels (stereo).

If the loop's total length is exactly the same as src's length, you might hear noises around the loop joint. This noise can be heard especially when src is decoded from a lossy compression format like Ogg/Vorbis and MP3. In this case, try to add more (about 0.1[s]) data to src after the loop end. If src has data after the loop end, an InfiniteLoop uses part of the data to blend with the loop start to make the loop joint smooth.

func NewInfiniteLoopF32 added in v2.8.0

func NewInfiniteLoopF32(src io.ReadSeeker, length int64) *InfiniteLoop

NewInfiniteLoopF32 creates a new infinite loop stream with a source stream and length in bytes.

src is a 32bit float little endian stream, 2 channels (stereo).

If the loop's total length is exactly the same as src's length, you might hear noises around the loop joint. This noise can be heard especially when src is decoded from a lossy compression format like Ogg/Vorbis and MP3. In this case, try to add more (about 0.1[s]) data to src after the loop end. If src has data after the loop end, an InfiniteLoop uses part of the data to blend with the loop start to make the loop joint smooth.

func NewInfiniteLoopWithIntro

func NewInfiniteLoopWithIntro(src io.ReadSeeker, introLength int64, loopLength int64) *InfiniteLoop

NewInfiniteLoopWithIntro creates a new infinite loop stream with an intro part. NewInfiniteLoopWithIntro accepts a source stream src, introLength in bytes and loopLength in bytes.

src is a signed 16bit integer little endian stream, 2 channels (stereo).

If the loop's total length is exactly the same as src's length, you might hear noises around the loop joint. This noise can be heard especially when src is decoded from a lossy compression format like Ogg/Vorbis and MP3. In this case, try to add more (about 0.1[s]) data to src after the loop end. If src has data after the loop end, an InfiniteLoop uses part of the data to blend with the loop start to make the loop joint smooth.

func NewInfiniteLoopWithIntroF32 added in v2.8.0

func NewInfiniteLoopWithIntroF32(src io.ReadSeeker, introLength int64, loopLength int64) *InfiniteLoop

NewInfiniteLoopWithIntroF32 creates a new infinite loop stream with an intro part. NewInfiniteLoopWithIntroF32 accepts a source stream src, introLength in bytes and loopLength in bytes.

src is a 32bit float little endian stream, 2 channels (stereo).

If the loop's total length is exactly the same as src's length, you might hear noises around the loop joint. This noise can be heard especially when src is decoded from a lossy compression format like Ogg/Vorbis and MP3. In this case, try to add more (about 0.1[s]) data to src after the loop end. If src has data after the loop end, an InfiniteLoop uses part of the data to blend with the loop start to make the loop joint smooth.

func (*InfiniteLoop) Read

func (i *InfiniteLoop) Read(b []byte) (int, error)

Read is implementation of ReadSeeker's Read.

func (*InfiniteLoop) Seek

func (i *InfiniteLoop) Seek(offset int64, whence int) (int64, error)

Seek is implementation of ReadSeeker's Seek.

type Player

type Player struct {
	// contains filtered or unexported fields
}

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.

func NewPlayer deprecated

func NewPlayer(context *Context, src io.Reader) (*Player, error)

NewPlayer creates a new player with the given stream.

Deprecated: as of v2.2. Use (*Context).NewPlayer instead.

func NewPlayerFromBytes deprecated

func NewPlayerFromBytes(context *Context, src []byte) *Player

NewPlayerFromBytes creates a new player with the given bytes.

Deprecated: as of v2.2. Use (*Context).NewPlayerFromBytes instead.

func (*Player) Close

func (p *Player) Close() error

Close closes the stream.

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.

func (*Player) Current deprecated

func (p *Player) Current() time.Duration

Current returns the current position in time.

Deprecated: as of v2.6. Use Position instead.

func (*Player) IsPlaying

func (p *Player) IsPlaying() bool

IsPlaying returns boolean indicating whether the player is playing.

func (*Player) Pause

func (p *Player) Pause()

Pause pauses the playing.

func (*Player) Play

func (p *Player) Play()

Play plays the stream.

func (*Player) Position added in v2.6.0

func (p *Player) Position() time.Duration

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 (*Player) Rewind

func (p *Player) Rewind() error

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 (*Player) Seek deprecated

func (p *Player) Seek(offset time.Duration) error

Seek seeks the position with the given offset.

Deprecated: as of v2.6. Use SetPosition instead.

func (*Player) SetBufferSize added in v2.3.0

func (p *Player) SetBufferSize(bufferSize time.Duration)

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 (*Player) SetPosition added in v2.6.0

func (p *Player) SetPosition(offset time.Duration) error

SetPosition sets the position with the given offset.

The passed source to NewPlayer must be io.Seeker, or SetPosition panics.

SetPosition returns error when seeking the source stream returns an error.

func (*Player) SetVolume

func (p *Player) SetVolume(volume float64)

SetVolume sets the volume of this player. volume must be in between 0 and 1. SetVolume panics otherwise.

func (*Player) Volume

func (p *Player) Volume() float64

Volume returns the current volume of this player [0-1].

Directories

Path Synopsis
internal
Package mp3 provides MP3 decoder.
Package mp3 provides MP3 decoder.
Package vorbis provides Ogg/Vorbis decoder.
Package vorbis provides Ogg/Vorbis decoder.
Package wav provides WAV (RIFF) decoder.
Package wav provides WAV (RIFF) decoder.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL