README

Mix

Build Status GoDoc codebeat badge Awesome

https://gopkg.in/mix.v0

Sequence-based Go-native audio mixer for music apps

See demo/demo.go:

package main

import (
  "fmt"
  "os"
  "time"
  
  "gopkg.in/mix.v0"
  "gopkg.in/mix.v0/bind"
)

var (
  sampleHz   = float64(48000)
  spec = bind.AudioSpec{
    Freq:     sampleHz,
    Format:   bind.AudioF32,
    Channels: 2,
    }
  bpm        = 120
  step       = time.Minute / time.Duration(bpm*4)
  loops      = 16
  prefix     = "sound/808/"
  kick1      = "kick1.wav"
  kick2      = "kick2.wav"
  marac      = "maracas.wav"
  snare      = "snare.wav"
  hitom      = "hightom.wav"
  clhat      = "cl_hihat.wav"
  pattern    = []string{
    kick2,
    marac,
    clhat,
    marac,
    snare,
    marac,
    clhat,
    kick2,
    marac,
    marac,
    hitom,
    marac,
    snare,
    kick1,
    clhat,
    marac,
  }
)

func main() {
  defer mix.Teardown()    
  
  mix.Debug(true)
  mix.Configure(spec)
  mix.SetSoundsPath(prefix)
  mix.StartAt(time.Now().Add(1 * time.Second))

  t := 2 * time.Second // padding before music
  for n := 0; n < loops; n++ {
    for s := 0; s < len(pattern); s++ {
      mix.SetFire(pattern[s], t+time.Duration(s)*step, 0, 1.0, 0)
    }
    t += time.Duration(len(pattern)) * step
  }

  fmt.Printf("Mix, pid:%v, spec:%v\n", os.Getpid(), spec)
  for mix.FireCount() > 0 {
    time.Sleep(1 * time.Second)
  }
}

Play this Demo from the root of the project, with no actual audio playback:

make demo

Or export WAV via stdout > demo/output.wav:

make demo.wav
Credit

Charney Kaye

XJ Music Inc.

What?

Game audio mixers are designed to play audio spontaneously, but when the timing is known in advance (e.g. sequence-based music apps) there is a demand for much greater accuracy in playback timing.

Read the API documentation at godoc.org/gopkg.in/mix.v0

Mix seeks to solve the problem of audio mixing for the purpose of the playback of sequences where audio files and their playback timing is known in advance.

Mix stores and mixes audio in native Go []float64 and natively implements Paul Vögler's "Loudness Normalization by Logarithmic Dynamic Range Compression" (details below)

Best efforts will be made to preserve each API version in a release tag that can be parsed, e.g. gopkg.in/mix.v0

Why?

Even after selecting a hardware interface library such as PortAudio or C++ SDL 2.0, there remains a critical design problem to be solved.

This design is a music application mixer. Most available options are geared towards Game development.

Game audio mixers offer playback timing accuracy +/- 2 milliseconds. But that's totally unacceptable for music, specifically sequence-based sample playback.

The design pattern particular to Game design is that the timing of the audio is not know in advance- the timing that really matters 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, mix seeks to solve the problem of audio mixing 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 the audio interface.

Mix takes maximum advantage of Go by storing and mixing audio in native Go []float64 and natively implementing Paul Vögler's "Loudness Normalization by Logarithmic Dynamic Range Compression"

Time

To the Mix API, time is specified as a time.Duration-since-epoch, where the epoch is the moment that mix.Start() was called.

Internally, time is tracked as samples-since-epoch at the master out playback frequency (e.g. 48000 Hz). This is most efficient because source audio is pre-converted to the master out playback frequency, and all audio maths are performed in terms of samples.

The Mixing Algorithm

Inspired 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 a demo implementation of mix included in the demo/ folder in this repository. Run it using the defaults:

cd demo && go get && go run demo.go

Or specify options, e.g. using WAV bytes to stdout for playback (piped to system native aplay)

go run demo.go --out wav | aplay

To show the help screen:

go run demo.go --help

Documentation

Overview

Sequence-based Go-native audio mixer for music apps

Go-native audio mixer for Music apps

See `demo/demo.go`:

package main

import (
  "fmt"
  "os"
  "time"

  "gopkg.in/mix.v0"
  "gopkg.in/mix.v0/bind"
)

var (
  sampleHz   = float64(48000)
  spec = bind.AudioSpec{
    Freq:     sampleHz,
    Format:   bind.AudioF32,
    Channels: 2,
    }
  bpm        = 120
  step       = time.Minute / time.Duration(bpm*4)
  loops      = 16
  prefix     = "sound/808/"
  kick1      = "kick1.wav"
  kick2      = "kick2.wav"
  marac      = "maracas.wav"
  snare      = "snare.wav"
  hitom      = "hightom.wav"
  clhat      = "cl_hihat.wav"
  pattern    = []string{
    kick2,
    marac,
    clhat,
    marac,
    snare,
    marac,
    clhat,
    kick2,
    marac,
    marac,
    hitom,
    marac,
    snare,
    kick1,
    clhat,
    marac,
  }
)

func main() {
  defer mix.Teardown()

  mix.Debug(true)
  mix.Configure(spec)
  mix.SetSoundsPath(prefix)
  mix.StartAt(time.Now().Add(1 * time.Second))

  t := 2 * time.Second // padding before music
  for n := 0; n < loops; n++ {
    for s := 0; s < len(pattern); s++ {
      mix.SetFire(pattern[s], t+time.Duration(s)*step, 0, 1.0, 0)
    }
    t += time.Duration(len(pattern)) * step
  }

  fmt.Printf("Mix, pid:%v, spec:%v\n", os.Getpid(), spec)
  for mix.FireCount() > 0 {
    time.Sleep(1 * time.Second)
  }
}

Play this Demo from the root of the project, with no actual audio playback

make demo

Or export WAV via stdout `> demo/output.wav`:

make demo.wav

What

Game audio mixers are designed to play audio spontaneously, but when the timing is known in advance (e.g. sequence-based music apps) there is a demand for much greater accuracy in playback timing.

Read the API documentation at https://godoc.org/gopkg.in/mix.v0

Mix seeks to solve the problem of audio mixing for the purpose of the playback of sequences where audio files and their playback timing is known in advance.

Mix stores and mixes audio in native Go `[]float64` and natively implements Paul Vögler's "Loudness Normalization by Logarithmic Dynamic Range Compression" (details below)

Credit

Charney Kaye https://charneykaye.com

XJ Music Inc. https://xj.io

Why

Even after selecting a hardware interface library such as http://www.portaudio.com/ or https://www.libsdl.org/, there remains a critical design problem to be solved.

This design is a music application mixer. Most available options are geared towards Game development.

Game audio mixers offer playback timing accuracy +/- 2 milliseconds. But that's totally unacceptable for music, specifically sequence-based sample playback.

The design pattern particular to Game design is that the timing of the audio is not know in advance- the timing that really matters 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, mix seeks to solve the problem of audio mixing 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 the audio interface.

Mix takes maximum advantage of Go by storing and mixing audio in native Go `[]float64` and natively implementing Paul Vögler's "Loudness Normalization by Logarithmic Dynamic Range Compression" (see The Mixing Algorithm below)

Time

To the Mix API, time is specified as a time.Duration-since-epoch, where the epoch is the moment that mix.Start() was called.

Internally, time is tracked as samples-since-epoch at the master out playback frequency (e.g. 48000 Hz). This is most efficient because source audio is pre-converted to the master out playback frequency, and all audio maths are performed in terms of samples.

The Mixing Algorithm

Inspired 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. This paper is published at http://www.voegler.eu/pub/audio/digital-audio-mixing-and-normalization.html.

Usage

There's a demo implementation of **mix** included in the `demo/` folder in this repository. Run it using the defaults:

cd demo && go get && go run demo.go

Or specify options, e.g. using WAV bytes to stdout for playback (piped to system native `aplay`)

go run demo.go --out wav | aplay

To show the help screen:

go run demo.go --help

Best efforts will be made to preserve each API version in a release tag that can be parsed, e.g. http://gopkg.in/mix.v0

Mix in good health!

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ClearAllFires

func ClearAllFires()

    ClearAllFires to clear all fires currently ready, or live

    func Configure

    func Configure(s spec.AudioSpec)

      Configure the mixer frequency, format, channels & sample rate.

      func Debug

      func Debug(isOn bool)

        Debug ON/OFF (ripples down to all sub-modules)

        func FireCount

        func FireCount() int

          FireCount to check the number of fires currently scheduled for playback

          func GetNowAt

          func GetNowAt() time.Duration

            GetNowAt returns current mix position

            func GetStartTime

            func GetStartTime() time.Time

              GetStartTime the mixer was started at

              func OutputClose

              func OutputClose()

                OutputBegin to output WAV closer as []byte via stdout

                func OutputContinueTo

                func OutputContinueTo(t time.Duration)

                  OutputContinueTo output as []byte via stdout, up to a specified duration-since-start

                  func OutputStart

                  func OutputStart(length time.Duration, out io.Writer)

                    OutputStart requires a known length

                    func SetFire

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

                      SetFire to represent a single audio source playing at a specific time in the future (in time.Duration from play start), with sustain time.Duration, volume from 0 to 1, and pan from -1 to +1

                      func SetMixCycleDuration

                      func SetMixCycleDuration(d time.Duration)

                        Set the duration between "mix cycles", wherein garbage collection is performed.

                        func SetSoundsPath

                        func SetSoundsPath(prefix string)

                          SetSoundsPath prefix

                          func Spec

                          func Spec() *spec.AudioSpec

                            Spec for the mixer, which may include callback functions, e.g. portaudio

                            func Start

                            func Start()

                              Start the mixer now

                              func StartAt

                              func StartAt(t time.Time)

                                StartAt a specific time in the future

                                func Teardown

                                func Teardown()

                                  Teardown everything and release all memory.

                                  Types

                                  This section is empty.

                                  Source Files

                                  Directories

                                  Path Synopsis
                                  Package bind is for modular binding of mix to audio interface
                                  Package bind is for modular binding of mix to audio interface
                                  debug
                                  Package debug for debugging
                                  Package debug for debugging
                                  hardware/null
                                  Package null is for modular binding of mix to a null (mock) audio interface
                                  Package null is for modular binding of mix to a null (mock) audio interface
                                  opt
                                  Package opt specifies valid options
                                  Package opt specifies valid options
                                  sample
                                  Package sample models an audio sample Package sample models an audio sample
                                  Package sample models an audio sample Package sample models an audio sample
                                  sox
                                  Package sox is for file I/O via go-sox package
                                  Package sox is for file I/O via go-sox package
                                  spec
                                  Package spec specifies valid audio formats
                                  Package spec specifies valid audio formats
                                  wav
                                  Package wav is direct WAV filo I/O Package wav is direct WAV filo I/O Package wav is direct WAV filo I/O Package wav is direct WAV filo I/O
                                  Package wav is direct WAV filo I/O Package wav is direct WAV filo I/O Package wav is direct WAV filo I/O Package wav is direct WAV filo I/O
                                  lib
                                  fire
                                  Package fire model an audio source playing at a specific time
                                  Package fire model an audio source playing at a specific time
                                  mix
                                  Package mix combines sources into an output audio stream
                                  Package mix combines sources into an output audio stream
                                  source
                                  Package source models a single audio source Package source models a single audio source
                                  Package source models a single audio source Package source models a single audio source