audio

package module
v0.0.0-...-ea4d24e Latest Latest
Warning

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

 Go to latest Published: Sep 26, 2021 License: Apache-2.0 Imports: 10 Imported by: 0

README

Package audio

The audio package implements audio decoding and playback in a manner mirroring the Audio module of SFML.

SFML stands for Simple and Fast Multimedia Library, a audio/graphics/windowing/networking library in C++. It is licensed under the Zlib/png license. I like it personally, being both fast, reliable and elegant in design.

Under the hood, the audio package wraps OpenAL for playback, and libFLAC, libVorbis and libOgg for decoding of FLAC and Ogg/Vorbis audio files.

import "github.com/Edgaru089/audio"
import _ "github.com/Edgaru089/audio/codec/flac"


audio.Init() // Initialize OpenAL

file, err := os.Open("Alstroemeria Records - Bad Apple!!.flac")

b := audio.NewSoundBuffer() // a large buffer keeping all the audio samples in memory
err := b.Load(file)

s := audio.NewSound() // the player of the sound buffer
s.SetBuffer(b)
s.Play()

m := audio.NewMusic() // a streaming audio object, keeping only a small piece of samples
err = m.Open(file)
m.Play()

Linking on Windows

In the extlib folder there are headers and library for mingw in 32 and 64 bits. The OpenAL part is linked dynamically and the file openal32.dll must be copied with the executable. libFLAC, libVorbis and libOgg are linked statically.

Things should work just fine.

Documentation

Overview

The audio package implements audio decoding and playback in a manner mirroring the Audio module of SFML.

SFML stands for Simple and Fast Multimedia Library, a audio/graphics/windowing/networking library in C++. It is licensed under the Zlib/png license. I like it personally, being both fast, reliable and elegant in design.

Under the hood, the audio package wraps OpenAL for playback, and libflac and libvorbis for decoding of FLAC and Ogg/Vorbis audio files.

Index

Constants

View Source 
const (
	SoundStreamBufferCount  = 3                     // number of audio buffers used by the stream thread
	SoundStreamRetries      = 2                     // number of retries (not counting first try) for GetData()
	SoundStreamPollInterval = 50 * time.Millisecond // interval between stream thread polling
)
View Source 
const (
	MusicBufferLength = time.Second // the length of the internal buffer of Music
)

Variables

This section is empty.

Functions

func GetGlobalVolume 

func GetGlobalVolume() float32

GetGlobalVolume returns the global volume of the listener, from 0 to 100.

The default is 100.

func GetListenerDirection 

func GetListenerDirection() [3]float32

GetListenerDirection sets the direction the global listener is facing.

the default is [0, 0, -1] (Z-Minus).

func GetListenerPosition 

func GetListenerPosition() [3]float32

GetListenerPosition returns the position of the global listener.

The default is [0, 0, 0].

func GetListenerUpVector 

func GetListenerUpVector() [3]float32

GetListenerUpVector returns the vector the global listener is pointing up towards.

the default is [0, 1, 0] (Y-Plus).

func Init 

func Init()

Init initializes OpenAL resources.

It should be called in the main function, preceeding any OpenAL calls.

func RegisterSoundFileReader 

func RegisterSoundFileReader(check SoundFileCheck, allocator func() SoundFileReader)

RegisterSoundFileReader registers a new SoundFileReader.

the allocator function allocates a new instance, it should look like 

func () { return &Decoder{} }

func SetGlobalVolume 

func SetGlobalVolume(volume float32)

SetGlobalVolume sets the global volume of the listener, from 0 to 100.

The default is 100.

func SetListenerDirection 

func SetListenerDirection(dir [3]float32)

SetListenerDirection sets the direction the global listener is facing.

The vector does not need to be normalized.

the default is [0, 0, -1] (Z-Minus).

func SetListenerPosition 

func SetListenerPosition(pos [3]float32)

SetListenerPosition sets the position of the global listener.

The default is [0, 0, 0].

func SetListenerUpVector 

func SetListenerUpVector(up [3]float32)

SetListenerUpVector sets the vector the global listener is pointing up towards.

The vector does not need to be normalized.

the default is [0, 1, 0] (Y-Plus).

Types

type Music 

type Music struct {
	SoundStream
	// contains filtered or unexported fields
}

Music is a streamed sound played from a InputSoundFile.

func NewMusic 

func NewMusic() (m *Music)

func (*Music) Close 

func (m *Music) Close()

func (*Music) Open 

func (m *Music) Open(file io.ReadSeeker) (err error)

func (*Music) SetAttenuation 

func (s *Music) SetAttenuation(attenuation float32)

SetAttenuation sets the attenuation factor of the sound.

The attenuation is a multiplicative factor which makes the sound more or less loud according to its distance from the listener. An attenuation of 0 will produce a non-attenuated sound, i.e. its volume will always be the same whether it is heard from near or from far. On the other hand, an attenuation value such as 100 will make the sound fade out very quickly as it gets further from the listener.

The default value of the attenuation is 1.

func (*Music) SetMinDistance 

func (s *Music) SetMinDistance(distance float32)

SetMinDistance sets the minimum distance of the sound.

The "minimum distance" of a sound is the maximum distance at which it is heard at its maximum volume. Further than the minimum distance, it will start to fade out according to its attenuation factor. A value of 0 ("inside the head of the listener") is an invalid value and is forbidden.

The default value of the minimum distance is 1.

func (*Music) SetPitch 

func (s *Music) SetPitch(pitch float32)

SetPitch sets the pitch of the sound.

The pitch represents the perceived fundamental frequency of a sound; thus you can make a sound more acute or grave by changing its pitch. A side effect of changing the pitch is to modify the playing speed of the sound as well.

The default value for the pitch is 1.

func (*Music) SetPosition 

func (s *Music) SetPosition(pos [3]float32)

SetPosition sets the 3D position of the sound in the audio scene.

Only sounds with one channel (mono sounds) can be spatialized.

The default position of a sound is (0, 0, 0).

func (*Music) SetRelativeToListener 

func (s *Music) SetRelativeToListener(relative bool)

SetRelativeToListener makes the sound's position relative to the listener or absolute.

Making a sound relative to the listener will ensure that it will always be played the same way regardless of the position of the listener. This can be useful for non-spatialized sounds, sounds that are produced by the listener, or sounds attached to it.

The default value is false (position is absolute).

func (*Music) SetVolume 

func (s *Music) SetVolume(volume float32)

SetVolume sets the volume of the sound.

The volume is a value between 0 (mute) and 100 (full volume).

The default value for the volume is 100.

type PlayStatus 

type PlayStatus int8

Enum object describing the play state of a sound. 

const (
	Stopped PlayStatus = iota // The sound is stopped (i.e., not playing)
	Paused                    // The sound is paused
	Playing                   // The sound is currently playing
)

type Sound 

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

func NewSound 

func NewSound() *Sound

NewSound creates a new empty Sound instance.

func (*Sound) Buffer 

func (s *Sound) Buffer() *SoundBuffer

Buffer returns the underlying buffer of the sound.

func (*Sound) Pause 

func (s *Sound) Pause()

Pause pauses the sound.

func (*Sound) Play 

func (s *Sound) Play()

Play starts or resumes playing the sound.

func (*Sound) PlayingOffset 

func (s *Sound) PlayingOffset() time.Duration

PlayingOffset returns the playing position of the sound in time.

func (*Sound) SetAttenuation 

func (s *Sound) SetAttenuation(attenuation float32)

SetAttenuation sets the attenuation factor of the sound.

The attenuation is a multiplicative factor which makes the sound more or less loud according to its distance from the listener. An attenuation of 0 will produce a non-attenuated sound, i.e. its volume will always be the same whether it is heard from near or from far. On the other hand, an attenuation value such as 100 will make the sound fade out very quickly as it gets further from the listener.

The default value of the attenuation is 1.

func (*Sound) SetBuffer 

func (s *Sound) SetBuffer(buf *SoundBuffer)

SetBuffer sets the underlying buffer of the sound.

func (*Sound) SetMinDistance 

func (s *Sound) SetMinDistance(distance float32)

SetMinDistance sets the minimum distance of the sound.

The "minimum distance" of a sound is the maximum distance at which it is heard at its maximum volume. Further than the minimum distance, it will start to fade out according to its attenuation factor. A value of 0 ("inside the head of the listener") is an invalid value and is forbidden.

The default value of the minimum distance is 1.

func (*Sound) SetPitch 

func (s *Sound) SetPitch(pitch float32)

SetPitch sets the pitch of the sound.

The pitch represents the perceived fundamental frequency of a sound; thus you can make a sound more acute or grave by changing its pitch. A side effect of changing the pitch is to modify the playing speed of the sound as well.

The default value for the pitch is 1.

func (*Sound) SetPlayingOffset 

func (s *Sound) SetPlayingOffset(offset time.Duration)

SetPlayingOffset changes the playing position of the sound.

It can be called when the sound is playing or paused. Calling on a stopped sound has no effect.

func (*Sound) SetPosition 

func (s *Sound) SetPosition(pos [3]float32)

SetPosition sets the 3D position of the sound in the audio scene.

Only sounds with one channel (mono sounds) can be spatialized.

The default position of a sound is (0, 0, 0).

func (*Sound) SetRelativeToListener 

func (s *Sound) SetRelativeToListener(relative bool)

SetRelativeToListener makes the sound's position relative to the listener or absolute.

Making a sound relative to the listener will ensure that it will always be played the same way regardless of the position of the listener. This can be useful for non-spatialized sounds, sounds that are produced by the listener, or sounds attached to it.

The default value is false (position is absolute).

func (*Sound) SetVolume 

func (s *Sound) SetVolume(volume float32)

SetVolume sets the volume of the sound.

The volume is a value between 0 (mute) and 100 (full volume).

The default value for the volume is 100.

func (*Sound) Status 

func (s *Sound) Status() PlayStatus

Status returns the current status of the sound stream.

func (*Sound) Stop 

func (s *Sound) Stop()

Stop stops playing the sound.

type SoundBuffer 

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

SoundBuffer holds sound sample data, together with a OpenAL resource tag pointing to the buffer.

SoundBuffers load all the sound data uncompressed into memory, so they tend to occupy a lot of room.

func NewSoundBuffer 

func NewSoundBuffer() *SoundBuffer

func (*SoundBuffer) ChannelCount 

func (b *SoundBuffer) ChannelCount() int

ChannelCount returns the number of channels in the buffer.

func (*SoundBuffer) Duration 

func (b *SoundBuffer) Duration() time.Duration

Duration returns the duration of the sound in the buffer.

func (*SoundBuffer) Load 

func (b *SoundBuffer) Load(file io.ReadSeeker) (err error)

Load loads the sound buffer with the given file.

Please, please don't load it again if a Sound is already using it. This may cause weird issues I cannot diagnose.

func (*SoundBuffer) SampleCount 

func (b *SoundBuffer) SampleCount() int64

SampleCount returns the number of samples in the buffer.

Two samples from two channels at the same timepoint count twice.

func (*SoundBuffer) SampleRate 

func (b *SoundBuffer) SampleRate() int

SampleRate returns the sample rate of the buffer, in samples per second.

func (*SoundBuffer) Samples 

func (b *SoundBuffer) Samples() []int16

Samples returns the internal samples buffer.

type SoundFileCheck 

type SoundFileCheck func(file io.ReadSeeker) (ok bool)

SoundFileCheck is called to tell if the given file can be handled by a codec.

The file is seeked to the beginning when the function is called.

func SoundFileCheckMagic 

func SoundFileCheckMagic(magic []byte, offset int64) SoundFileCheck

SoundFileCheckMagic returns a function that returns true if the file begins with the given magic string at the given offset.

type SoundFileInfo 

type SoundFileInfo struct {
	SampleCount  int64 // Total numbers of samples in the file, 2 channels count as 2
	ChannelCount int   // Numbers of channels in the file
	SampleRate   int   // Sample rate of the file, in samples per second
}

SoundFileInfo contains the properities of a audio file.

func (SoundFileInfo) String 

func (s SoundFileInfo) String() string

type SoundFileReader 

type SoundFileReader interface {

	// Open opens a file stream for future decoding.
	//
	// The file stream is already seeked to the beginning, i.e.,
	// have file.Seek(0, io.SeekStart) called.
	//
	// A single SoundFileReader instance should only call Open once.
	Open(file io.ReadSeeker) (SoundFileInfo, error)

	// Info returns the properities of the sound stream.
	Info() SoundFileInfo

	// Seek changes the read position to the given offset, relative to the beginning of the file.
	//
	// The sampleOffset can be computed from Time offset with the given formula:
	//     timeInSeconds * sampleRate * channelCount
	//
	// If sampleOffset is greater than the number of samples in the file,
	// this function must jump to the end of the file.
	Seek(sampleOffset int64) error

	// Read reads audio samples from the open file.
	//
	// The read data is written into the len() part of the data slice.
	//
	// The returned number of samples read may be smaller than len(data).
	// This should not be considered as an error only on EOF.
	//
	// On end-of-file, Read should return (0, io.EOF).
	Read(data []int16) (samplesRead int64, err error)

	// The reader needs to be closed after use.
	io.Closer
}

SoundFileReader is a interface to be implemented by sound file decoders.

Sound file codecs also need to implement the SoundFileCheck function.

func NewSoundFileReader 

func NewSoundFileReader(file io.ReadSeeker) SoundFileReader

NewSoundFileReader creates a new SoundFileReader from the registered codecs.

It DOES NOT call reader.Open().

It returns nil if no matching SoundFileReader is found.

type SoundStream 

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

SoundStream implements a basis for streamed audio content.

func (*SoundStream) ChannelCount 

func (s *SoundStream) ChannelCount() int

ChannelCount returns the number of channels in the buffer.

func (*SoundStream) Close 

func (s *SoundStream) Close()

Close closes the SoundStream. It also ends the goroutine tied to it.

The stream object should not be used again.

func (*SoundStream) Duration 

func (s *SoundStream) Duration() time.Duration

Duration returns the duration of the sound in the buffer.

func (*SoundStream) Init 

func (s *SoundStream) Init(iface SoundStreamInterface, info SoundFileInfo)

Init is called by derived classes to initialize the sound stream.

func (*SoundStream) Pause 

func (s *SoundStream) Pause()

Pause pauses the sound stream if playing.

func (*SoundStream) Play 

func (s *SoundStream) Play()

Play starts/resumes playing the sound stream.

It restarts the stream from the beginning if it is already playing.

func (*SoundStream) PlayingOffset 

func (s *SoundStream) PlayingOffset() time.Duration

PlayingOffset returns the playing position of the sound in time.

func (*SoundStream) SampleCount 

func (s *SoundStream) SampleCount() int64

SampleCount returns the number of samples in the buffer.

Two samples from two channels at the same timepoint count twice.

func (*SoundStream) SampleRate 

func (s *SoundStream) SampleRate() int

SampleRate returns the sample rate of the buffer, in samples per second.

func (*SoundStream) SetAttenuation 

func (s *SoundStream) SetAttenuation(attenuation float32)

SetAttenuation sets the attenuation factor of the sound.

The attenuation is a multiplicative factor which makes the sound more or less loud according to its distance from the listener. An attenuation of 0 will produce a non-attenuated sound, i.e. its volume will always be the same whether it is heard from near or from far. On the other hand, an attenuation value such as 100 will make the sound fade out very quickly as it gets further from the listener.

The default value of the attenuation is 1.

func (*SoundStream) SetMinDistance 

func (s *SoundStream) SetMinDistance(distance float32)

SetMinDistance sets the minimum distance of the sound.

The "minimum distance" of a sound is the maximum distance at which it is heard at its maximum volume. Further than the minimum distance, it will start to fade out according to its attenuation factor. A value of 0 ("inside the head of the listener") is an invalid value and is forbidden.

The default value of the minimum distance is 1.

func (*SoundStream) SetPitch 

func (s *SoundStream) SetPitch(pitch float32)

SetPitch sets the pitch of the sound.

The pitch represents the perceived fundamental frequency of a sound; thus you can make a sound more acute or grave by changing its pitch. A side effect of changing the pitch is to modify the playing speed of the sound as well.

The default value for the pitch is 1.

func (*SoundStream) SetPlayingOffset 

func (s *SoundStream) SetPlayingOffset(offset time.Duration)

SetPlayingOffset changes the playing position of the sound.

It can be called when the sound is playing or paused. Calling on a stopped sound has no effect.

func (*SoundStream) SetPosition 

func (s *SoundStream) SetPosition(pos [3]float32)

SetPosition sets the 3D position of the sound in the audio scene.

Only sounds with one channel (mono sounds) can be spatialized.

The default position of a sound is (0, 0, 0).

func (*SoundStream) SetRelativeToListener 

func (s *SoundStream) SetRelativeToListener(relative bool)

SetRelativeToListener makes the sound's position relative to the listener or absolute.

Making a sound relative to the listener will ensure that it will always be played the same way regardless of the position of the listener. This can be useful for non-spatialized sounds, sounds that are produced by the listener, or sounds attached to it.

The default value is false (position is absolute).

func (*SoundStream) SetVolume 

func (s *SoundStream) SetVolume(volume float32)

SetVolume sets the volume of the sound.

The volume is a value between 0 (mute) and 100 (full volume).

The default value for the volume is 100.

func (*SoundStream) Status 

func (s *SoundStream) Status() PlayStatus

Status returns the current status of the sound stream.

func (*SoundStream) Stop 

func (s *SoundStream) Stop()

Stop stops the sound streaming if playing.

type SoundStreamInterface 

type SoundStreamInterface interface {
	// SoundGetData requests a new chunk of audio samples from the stream source.
	//
	// This function is called to provide the audio samples to play.
	// It is called continuously by the streaming loop, in a separate goroutine.
	//
	// The data inside the slice is copied, meaning that you can use the same buffer
	// over and over again.
	//
	// The source can choose to stop the streaming loop at any time, by
	// returning an empty slice.
	GetData() []int16

	// Seek changes the current playing position of the stream source.
	//
	// If the sound stream in question does not support seeking, this function
	// should do nothing.
	Seek(time time.Duration)
}

SoundStreamInterface wraps underlying streamed audio resource.

Source Files

View all Source files

Directories

Path Synopsis
codec
flac
Package flac wraps libflac to provide the parent audio package a codec for FLAC.
 Package flac wraps libflac to provide the parent audio package a codec for FLAC.
ogg
Package ogg wraps libvorbis to provide the parent audio package a codec for Ogg/Vorbis.
 Package ogg wraps libvorbis to provide the parent audio package a codec for Ogg/Vorbis.
wave

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.