Documentation

Overview

    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.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    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, error)

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

            func (c *Context) SampleRate() int

              SampleRate returns the sample rate.

              func (*Context) Update

              func (c *Context) Update() error

                Update does nothing.

                Deprecated: (as of 1.6.0) Do not use this.

                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.

                type InfiniteLoop

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

                  InfiniteLoop represents a looped stream which never ends.

                  func NewInfiniteLoop

                  func NewInfiniteLoop(src ReadSeekCloser, length int64) *InfiniteLoop

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

                    func NewInfiniteLoopWithIntro

                    func NewInfiniteLoopWithIntro(src ReadSeekCloser, 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.

                      func (*InfiniteLoop) Close

                      func (l *InfiniteLoop) Close() error

                        Close is implementation of ReadSeekCloser's Close.

                        func (*InfiniteLoop) Read

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

                          Read is implementation of ReadSeekCloser's Read.

                          func (*InfiniteLoop) Seek

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

                            Seek is implementation of ReadSeekCloser'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

                              func NewPlayer(context *Context, src io.ReadCloser) (*Player, 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 NewPlayerFromBytes

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

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

                                  func (p *Player) Close() error

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

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

                                      Current returns the current position in time.

                                      func (*Player) IsPlaying

                                      func (p *Player) IsPlaying() bool

                                        IsPlaying returns boolean indicating whether the player is playing.

                                        func (*Player) Pause

                                        func (p *Player) Pause() error

                                          Pause pauses the playing.

                                          Pause always returns nil.

                                          func (*Player) Play

                                          func (p *Player) Play() error

                                            Play plays the stream.

                                            Play always returns nil.

                                            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

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

                                                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 (*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].

                                                    type ReadSeekCloser

                                                    type ReadSeekCloser interface {
                                                    	io.ReadSeeker
                                                    	io.Closer
                                                    }

                                                      ReadSeekCloser is an io.ReadSeeker and io.Closer.

                                                      func BytesReadSeekCloser

                                                      func BytesReadSeekCloser(b []byte) ReadSeekCloser

                                                        BytesReadSeekCloser creates ReadSeekCloser from bytes.

                                                        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.