drum

Documentation

Overview

Package drum implements the decoding of .splice drum machine files.

To decode a file on disk, and retrieve the pattern stored in the file, use the DecodeFile() function:

pattern, err := DecodeFile("filename.splice")
if err == nil {
	fmt.Println(pattern)
}

For more advanced usage, you can use the DecodeReader() function, which works in the same way, but takes a reader as argument.

Once you have loaded the pattern, you can inspect it. Here are some examples:

p, _ := DecodeFile("filename.splice")
fmt.Println(p)
fmt.Println("* Longest track is", p.LongestTrack(), "beats")
fmt.Println("* Duration of pattern is", p.Duration())
fmt.Println("* One beat takes", p.BeatDuration())
fmt.Println("* First track instrument is", p.Tracks[0].Instrument)
fmt.Println("* At first beat we will play", p.PlayAt(0))

The output could then look like this:

Saved with HW Version: 0.808-alpha
Tempo: 120
(0) kick        |x---|x---|x---|x---|
(1) snare       |----|x---|----|x---|
(2) clap        |----|x-x-|----|----|
(3) hh-open     |--x-|--x-|x-x-|--x-|
(4) hh-close    |x---|x---|----|x--x|
(5) cowbell     |----|----|--x-|----|

* Longest track is 16 beats
* Duration of pattern is 8s
* One beat takes 500ms
* First track Instrument is (0) kick
* At first beat we will play [(0) kick (4) hh-close]

Index

• Constants
• Variables
• type Instrument
  • func (i Instrument) String() string
• type Pattern
  • func DecodeFile(path string) (*Pattern, error)
  • func DecodeReader(r io.Reader) (*Pattern, error)
  • func (p Pattern) BeatDuration() time.Duration
  • func (p *Pattern) Decode(r io.Reader) error
  • func (p Pattern) Duration() time.Duration
  • func (p Pattern) LongestTrack() int
  • func (p Pattern) PlayAt(x int) []Instrument
  • func (p Pattern) String() string
• type Step
• type Track
  • func (t Track) At(x int) Step
  • func (t Track) Len() int
  • func (t Track) String() string

Constants

const SpliceTrackLength = 16

Fixed track length in SPLICE format.

Variables

var ErrFileTooSmall = errors.New("file is too small to contain tracks")

This error is returned if the file is too small to be decoded. It is likely the file has been truncated.

var ErrInstrumentName = errors.New("unable to read the instument name")

ErrInstrumentName will be returned when the track decoder is unable to decode the instrument name.

var ErrMagicCode = errors.New("magic code for splice does not match")

This will be returned, if the magic value "SPLICE" isn't found in the beginning of a pattern file.

var ErrPayloadTooBig = errors.New("payload size too big")

ErrPayloadTooBig will be returned if the payload size of the file is considered too big. The value is set to 2^24 bytes, which allows for patterns up to 16MB.

Types

type Instrument

type Instrument struct {
	ID   uint8
	Name string
}

An Instrument is the representation of an instrument used by a track.

func (Instrument) String

func (i Instrument) String() string

String returns a human readable representation of the instrument.

type Pattern

type Pattern struct {
	Tempo   float32 // Tempo in beats per minute (bpm)
	Version string  // Software version that saved the track
	Tracks  []Track // Will contain individual tracks
}

A Pattern is the high level representation of the drum pattern contained in a .splice file.

func DecodeFile

func DecodeFile(path string) (*Pattern, error)

DecodeFile decodes the drum machine file found at the provided path and returns a pointer to a parsed pattern which is the entry point to the rest of the data. If the file cannot be found, an instance of *os.PathError is returned.

func DecodeReader

func DecodeReader(r io.Reader) (*Pattern, error)

DecodeReader decodes the drum machine from the supplied reader and return a pointer to a parsed pattern which is the entry point to the rest of the data.

func (Pattern) BeatDuration

func (p Pattern) BeatDuration() time.Duration

BeatDuration returns the duration of a single beat.

func (*Pattern) Decode

func (p *Pattern) Decode(r io.Reader) error

Decode will decode a pattern into p. On succcessful decode, p will contain the information from the file, and the reader will be placed after the last byte of the payload. If an error occurs it will be returned, and p may contain partial data that has been read.

func (Pattern) Duration

func (p Pattern) Duration() time.Duration

Duration returns the duration of the pattern. If the length of the individual tracks diverge, the longest duration is returned.

func (Pattern) LongestTrack

func (p Pattern) LongestTrack() int

LongestTrack returns the number of beats of the longest track. If no tracks are present, 0 is returned.

func (Pattern) PlayAt

func (p Pattern) PlayAt(x int) []Instrument

PlayAt returns the instruments to play at beat 'x'. Individual tracks will loop once they have finished playing. If x is negative nothing will be returned.

func (Pattern) String

func (p Pattern) String() string

String will return a printable string representation of the Pattern

type Step

type Step byte

A Step indicated what action should be taken at a given step

const (
	// StepNothing indicates that nothing should happend this step
	StepNothing Step = iota
	// StepPlay indicated that the instrument should be played this step
	StepPlay
)

type Track

type Track struct {
	Instrument Instrument // The instrument used for this track
	Steps      []Step     // Individual steps
}

A Track is a representation, representin an instrument and an indication of whether the instrument should be played at a given step.

func (Track) At

func (t Track) At(x int) Step

At returns the step value at x The value loops after the length of the tracks. Negative values of x will always return StepNothing

func (Track) Len

func (t Track) Len() int

Len returns the number beats in this track.

func (Track) String

func (t Track) String() string

Returns a human readable representation of the track.