atomix

README

Atomix

Sequence-based mixer for Music apps, built on go-sdl2.

Read the API documentation at godoc.org/github.com/outrightmental/go-atomix

Atomix seeks to solve the problem of audio mixing on top of bare SDL, specifically for the purpose of the playback of sequences where audio files and their playback timing is known in advance.

Though it is called via C bindings by the SDL audio callback, atomix stores and mixes audio in native Go []float64

Built on go-sdl2 - Go bindings for the C++ library "Simple DirectMedia Layer" SDL 2.0

Author: Charney Kaye

Copyright 2015 Outright Mental, Inc.

Why?

For sequence mixing in music application development.

Following principles of modularity and reusability according to The Unix Philosophy and

go-sdl2 is excellent, yet still leaves a design problem to be solved, that was equally inherent when using the original C++ SDL 2.0 library.

This design problem is a music application mixer. Most available options are geared towards Game development, including the proprietary SDL_mixer project for which the go-sdl2 team has also implemented bindings. The design pattern particular to Game design is that the timing of the audio is not know in advance- the timing that really matterns is that which is assembled in near-real-time in response to user interaction.

In the field of Music development, often the timing is known in advance, e.g. a *sequencer, the composition of music by specifying exactly how, when and which audio files will be played relative to the beginning of playback.

Ergo, atomix seeks to solve the problem of audio mixing on top of bare SDL, specifically for the purpose of the playback of sequences where audio files and their playback timing is known in advance. It seeks to do this with the absolute minimal logical overhead on top of SDL.

Though it is called via C bindings by the SDL audio callback, atomix stores and mixes audio in native Go []float64

The Mixing Algorithm

Insipired by the theory paper "Mixing two digital audio streams with on the fly Loudness Normalization by Logarithmic Dynamic Range Compression" by Paul Vögler, 2012-04-20. A .PDF has been included here, from the paper originally published here.

Usage

There's an example implementation of go-sdl2 + go-atomix included in the example/ folder in this repository.

Documentation

Overview

* Copyright 2015 Outright Mental, Inc.

* Copyright 2015 Outright Mental, Inc.

* Copyright 2015 Outright Mental, Inc.

* Copyright 2015 Outright Mental, Inc.

Index

• Constants
• func AudioCallback(userdata unsafe.Pointer, stream *C.Uint8, length C.int)
• func Configure(spec sdl.AudioSpec)
• func Debug(isOn bool)
• func SetFire(source string, begin time.Duration, sustain time.Duration, volume float64, ...)
• func Spec() *sdl.AudioSpec
• func Start()
• func StartAt(t time.Time)
• func Teardown()
• type Fire
  • func NewFire(source string, beginTz Tz, endTz Tz, volume float64, pan float64) *Fire
  • func (f *Fire) At(at Tz) (t Tz)
  • func (f *Fire) IsAlive() bool
  • func (f *Fire) SetState(state FireStateEnum)
  • func (f *Fire) State() FireStateEnum
• type FireStateEnum
• type Mixer
  • func (m *Mixer) Debug(isOn bool)
  • func (m *Mixer) Debugf(format string, args ...interface{})
  • func (m *Mixer) Initialize()
  • func (m *Mixer) NextOutput(byteSize int) []byte
  • func (m *Mixer) SetFire(source string, begin time.Duration, sustain time.Duration, volume float64, ...)
  • func (m *Mixer) Start()
  • func (m *Mixer) StartAt(t time.Time)
  • func (m *Mixer) Teardown()
• type Source
  • func NewSource(URL string) *Source
  • func (s *Source) Load()
  • func (s *Source) SampleAt(at Tz) float64
  • func (s *Source) State() SourceStateEnum
  • func (s *Source) StateName() string
  • func (s *Source) Teardown()
• type SourceStateEnum
• type Tz

Constants

const VERSION = "0.0.1"

Functions

func AudioCallback

func AudioCallback(userdata unsafe.Pointer, stream *C.Uint8, length C.int)

func Configure

func Configure(spec sdl.AudioSpec)

func Debug

func Debug(isOn bool)

func SetFire

func SetFire(source string, begin time.Duration, sustain time.Duration, volume float64, pan float64)

func Spec

func Spec() *sdl.AudioSpec

func Start

func Start()

func StartAt

func StartAt(t time.Time)

func Teardown

func Teardown()

Types

type Fire

type Fire struct {
	/* setup */
	BeginTz Tz
	EndTz   Tz
	Source  string
	Volume  float64
	Pan     float64
	// contains filtered or unexported fields
}

func NewFire

func NewFire(source string, beginTz Tz, endTz Tz, volume float64, pan float64) *Fire

func (*Fire) At

func (f *Fire) At(at Tz) (t Tz)

func (*Fire) IsAlive

func (f *Fire) IsAlive() bool

func (*Fire) SetState

func (f *Fire) SetState(state FireStateEnum)

func (*Fire) State

func (f *Fire) State() FireStateEnum

type FireStateEnum

type FireStateEnum uint

const (
	FIRE_READY FireStateEnum = 1
	FIRE_PLAY  FireStateEnum = 2
	// it can be assumed that all alive states are < SOURCE_FINISHED
	FIRE_DONE FireStateEnum = 6
)

type Mixer

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

func (*Mixer) Debug

func (m *Mixer) Debug(isOn bool)

func (*Mixer) Debugf

func (m *Mixer) Debugf(format string, args ...interface{})

func (*Mixer) Initialize

func (m *Mixer) Initialize()

func (*Mixer) NextOutput

func (m *Mixer) NextOutput(byteSize int) []byte

func (*Mixer) SetFire

func (m *Mixer) SetFire(source string, begin time.Duration, sustain time.Duration, volume float64, pan float64)

func (*Mixer) Start

func (m *Mixer) Start()

func (*Mixer) StartAt

func (m *Mixer) StartAt(t time.Time)

func (*Mixer) Teardown

func (m *Mixer) Teardown()

type Source

type Source struct {
	URL string
	// contains filtered or unexported fields
}

func NewSource

func NewSource(URL string) *Source

func (*Source) Load

func (s *Source) Load()

func (*Source) SampleAt

func (s *Source) SampleAt(at Tz) float64

func (*Source) State

func (s *Source) State() SourceStateEnum

func (*Source) StateName

func (s *Source) StateName() string

func (*Source) Teardown

func (s *Source) Teardown()

type SourceStateEnum

type SourceStateEnum uint

const (
	SOURCE_LOADING SourceStateEnum = 1
	SOURCE_READY   SourceStateEnum = 2
	// it can be assumed that all alive states are < SOURCE_FINISHED
	SOURCE_FINISHED SourceStateEnum = 6
	SOURCE_FAILED   SourceStateEnum = 7
)

type Tz

type Tz uint64