smf

Documentation

Overview

Package smf provides constants and interfaces for reading and writing of Standard MIDI Files (SMF).

The readers/writers can be found here:

github.com/gomidi/midi/smf/smfreader (read MIDI messages from SMF)
github.com/gomidi/midi/smf/smfwriter (writes MIDI messages to SMF)

The MIDI messages that can be read/written from/to a SMF file can be found here:

github.com/gomidi/midi/midimessage/channel    (Channel Messages)
github.com/gomidi/midi/midimessage/cc         (Control Change Messages)
github.com/gomidi/midi/midimessage/meta       (Meta Messages)
github.com/gomidi/midi/midimessage/sysex      (System Exclusive Messages)

Index

• Constants
• type Chunk
  • func (c *Chunk) Clear()
  • func (c *Chunk) Len() int
  • func (c *Chunk) ReadHeader(rd io.Reader) (length uint32, err error)
  • func (c *Chunk) SetType(typ [4]byte)
  • func (c *Chunk) Type() string
  • func (c *Chunk) Write(b []byte) (int, error)
  • func (c *Chunk) WriteTo(wr io.Writer) error
• type Format
• type Header
  • func (h Header) String() string
• type MetricTicks
  • func (q MetricTicks) Duration(tempoBPM uint32, deltaTicks uint32) time.Duration
  • func (q MetricTicks) Number() uint16
  • func (q MetricTicks) String() string
  • func (q MetricTicks) Ticks(tempoBPM uint32, d time.Duration) (ticks uint32)
  • func (q MetricTicks) Ticks1024th() uint32
  • func (q MetricTicks) Ticks128th() uint32
  • func (q MetricTicks) Ticks16th() uint32
  • func (q MetricTicks) Ticks256th() uint32
  • func (q MetricTicks) Ticks32th() uint32
  • func (q MetricTicks) Ticks4th() uint32
  • func (q MetricTicks) Ticks512th() uint32
  • func (q MetricTicks) Ticks64th() uint32
  • func (q MetricTicks) Ticks8th() uint32
• type Reader
• type TimeCode
  • func SMPTE24(subframes uint8) TimeCode
  • func SMPTE25(subframes uint8) TimeCode
  • func SMPTE30(subframes uint8) TimeCode
  • func SMPTE30DropFrame(subframes uint8) TimeCode
  • func (t TimeCode) String() string
• type TimeFormat
• type Writer

Constants

const (
	// SMF0 represents the singletrack SMF format (0)
	SMF0 = format(0)

	// SMF1 represents the multitrack SMF format (1)
	SMF1 = format(1)

	// SMF2 represents the sequential track SMF format (2)
	SMF2 = format(2)
)

Types

type Chunk

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

Chunk is a chunk of a SMF file

func (*Chunk) Clear

func (c *Chunk) Clear()

Clear removes all data but keeps the type

func (*Chunk) Len

func (c *Chunk) Len() int

Len returns the length of the chunk body

func (*Chunk) ReadHeader

func (c *Chunk) ReadHeader(rd io.Reader) (length uint32, err error)

ReadHeader reads the header from the given reader returns the length of the following body for errors, length of 0 is returned

func (*Chunk) SetType

func (c *Chunk) SetType(typ [4]byte)

SetType sets the type of the chunk

func (*Chunk) Type

func (c *Chunk) Type() string

Type returns the type of the chunk (from the header)

func (*Chunk) Write

func (c *Chunk) Write(b []byte) (int, error)

Write writes the given bytes to the body of the chunk

func (*Chunk) WriteTo

func (c *Chunk) WriteTo(wr io.Writer) error

WriteTo writes the content of the chunk to the given writer

type Format

type Format interface {

	// String returns the string representation of the SMF format.
	String() string

	// Type returns the type of the SMF file: 0 for SMF0, 1 for SMF1 and 2 for SMF2
	Type() uint16
	// contains filtered or unexported methods
}

Format is the common interface of all SMF file formats

type Header

type Header struct {

	// Format is the SMF file format: SMF0, SMF1 or SMF2
	Format

	// NumTracks is the number of tracks (always > 0)
	NumTracks uint16

	// TimeFormat is the time format (either MetricTicks or TimeCode)
	TimeFormat
}

Header represents the header of a SMF file.

func (Header) String

func (h Header) String() string

type MetricTicks

type MetricTicks uint16

MetricTicks represents the "ticks per quarter note" (metric) time format It defaults to 960 (i.e. 0 is treated as if it where 960 ticks per quarter note)

func (MetricTicks) Duration

func (q MetricTicks) Duration(tempoBPM uint32, deltaTicks uint32) time.Duration

Duration returns the time.Duration for a number of ticks at a certain tempo (in BPM)

func (MetricTicks) Number

func (q MetricTicks) Number() uint16

Number returns the number of the metric ticks (ticks for a quarter note, defaults to 960)

func (MetricTicks) String

func (q MetricTicks) String() string

String returns the string representation of the quarter note resolution

func (MetricTicks) Ticks

func (q MetricTicks) Ticks(tempoBPM uint32, d time.Duration) (ticks uint32)

Ticks returns the ticks for a given time.Duration at a certain tempo (in BPM)

func (MetricTicks) Ticks1024th

func (q MetricTicks) Ticks1024th() uint32

Ticks1024th returns the ticks for a 1024th note

func (MetricTicks) Ticks128th

func (q MetricTicks) Ticks128th() uint32

Ticks128th returns the ticks for a 128th note

func (MetricTicks) Ticks16th

func (q MetricTicks) Ticks16th() uint32

Ticks16th returns the ticks for a 16th note

func (MetricTicks) Ticks256th

func (q MetricTicks) Ticks256th() uint32

Ticks256th returns the ticks for a 256th note

func (MetricTicks) Ticks32th

func (q MetricTicks) Ticks32th() uint32

Ticks32th returns the ticks for a 32th note

func (MetricTicks) Ticks4th

func (q MetricTicks) Ticks4th() uint32

Ticks4th returns the ticks for a quarter note

func (MetricTicks) Ticks512th

func (q MetricTicks) Ticks512th() uint32

Ticks512th returns the ticks for a 512th note

func (MetricTicks) Ticks64th

func (q MetricTicks) Ticks64th() uint32

Ticks64th returns the ticks for a 64th note

func (MetricTicks) Ticks8th

func (q MetricTicks) Ticks8th() uint32

Ticks8th returns the ticks for a quaver note

type Reader

type Reader interface {

	// ReadHeader reads the header of the SMF file. If Header is called before ReadHeader, it will panic.
	// ReadHeader is also implicitly called with the first call of Read() (if it has not been run before)
	ReadHeader() error

	// Read reads a MIDI message from a SMF file.
	// any error will be tracked and stops reading and prevents any other attempt to read.
	// this first and last error is returned from Error()
	Read() (midi.Message, error)

	// Header returns the header of SMF file
	// if the header is not yet read, it will be read before
	// if any error occurred during reading of header, it can be found with Error()
	Header() Header

	// Delta returns the time distance between the last read midi message and the message before in ticks.
	// The meaning of a tick depends on the time format that is set in the header of the SMF file.
	Delta() (ticks uint32)

	// Track returns the number of the track of the last read midi message (starting with 0)
	// It returns -1 if no message has been read yet.
	Track() int16
}

Reader reads midi messages from a standard midi file (SMF) Reader is also a midi.Reader

type TimeCode

type TimeCode struct {
	FramesPerSecond uint8
	SubFrames       uint8
}

TimeCode is the SMPTE time format. It can be comfortable created with the SMPTE* functions.

func SMPTE24

func SMPTE24(subframes uint8) TimeCode

SMPTE24 returns a SMPTE24 TimeCode with the given subframes

func SMPTE25

func SMPTE25(subframes uint8) TimeCode

SMPTE25 returns a SMPTE25 TimeCode with the given subframes

func SMPTE30

func SMPTE30(subframes uint8) TimeCode

SMPTE30 returns a SMPTE30 TimeCode with the given subframes

func SMPTE30DropFrame

func SMPTE30DropFrame(subframes uint8) TimeCode

SMPTE30DropFrame returns a SMPTE30 drop frame TimeCode with the given subframes

func (TimeCode) String

func (t TimeCode) String() string

String represents the TimeCode as a string.

type TimeFormat

type TimeFormat interface {
	String() string
	// contains filtered or unexported methods
}

TimeFormat is the common interface of all SMF time formats

type Writer

type Writer interface {

	// Header returns the header
	Header() Header

	// WriteHeader writes the midi header
	// If WriteHeader was not called before the first run of Write,
	// it will implicitly be called when calling Write.
	WriteHeader() error

	// Write writes a midi message to the SMF file.
	//
	// Due to the nature of SMF files there is some maybe surprising behavior.
	// - If the header has not been written yet, it will be written before writing the first message.
	// - The first message will be written to track 0 which will be implicitly created.
	// - All messages of a track will be buffered inside the track and only be written if an EndOfTrack
	//   message is written.
	// - The number of tracks that are written will never execeed the NumTracks that have been defined when creating the writer.
	//   If the last track has been written, io.EOF will be returned. (Also for any further attempt to write).
	// - It is the responsibility of the caller to make sure the provided NumTracks (which defaults to 1) is not
	//   larger as the number of tracks in the file.
	// Keep the above in mind when examinating the written nbytes that are returned. They reflect the number of bytes
	// that have been physically written at that point in time.
	// any error stops the writing, is tracked and prohibits further writing.
	// this last error is returned from Error()
	Write(midi.Message) error

	// SetDelta sets a time distance between the last written and the following message in ticks.
	// The meaning of a tick depends on the time format that is set in the header of the SMF file.
	SetDelta(ticks uint32)
}

Writer writes midi messages to a standard midi file (SMF) Writer is also a midi.Writer