Transactional, resource-bounded SMF parser and authoring API. More...

#include <MidiFile.h>

Public Member Functions
bool	create (uint16_t format, uint16_t ppqn, size_t trackCount=1)
	Replaces the document with an empty writable format 0 or 1 file.

std::optional< size_t >	addTrack ()
	Adds an empty track to a format 1 document.

bool	addChannelEvent (size_t track, uint32_t delta, uint8_t status, uint8_t data1, uint8_t data2=0)
	Adds a validated MIDI channel event.

bool	addSysExEvent (size_t track, uint32_t delta, MidiEventKind f0OrF7, std::span< const uint8_t > payload)
	Adds an F0 or F7 SysEx packet event.

bool	addMetaEvent (size_t track, uint32_t delta, uint8_t type, std::span< const uint8_t > payload={})
	Adds an opaque meta event.

void	clear () noexcept
	Restores the empty-state sentinel.

bool	read (const std::filesystem::path &path)
	Reads and validates an SMF format 0, 1, or 2 file.

bool	write (const std::filesystem::path &path) const
	Writes a validated format 0 or 1 document.

int	format () const noexcept
	Returns 0, 1, or 2; returns -1 for an empty object.

uint16_t	ticksPerQuarter () const noexcept
	Returns PPQN, or zero for an empty object.

const std::vector< MidiTrack > &	tracks () const noexcept
	Returns immutable semantic tracks as an owner-thread reference view.

std::optional< std::vector< MidiTempoChange > >	tempoMap (size_t track=0) const
	Builds the effective tempo map for a track.

std::optional< uint64_t >	tickToMicroseconds (uint64_t tick, size_t track=0) const noexcept
	Converts an absolute tick to floor(exact elapsed microseconds).

std::optional< double >	tickToSeconds (uint64_t tick, size_t track=0) const noexcept
	Converts an absolute tick directly from the shared rational sum.

Static Public Attributes
static constexpr uint64_t	kMaxInputBytes = 256ull * 1024 * 1024
	Maximum accepted or produced file size.

static constexpr uint32_t	kMaxTracks = 4096
	Maximum number of track chunks.

static constexpr uint64_t	kMaxEvents = 2000000
	Maximum aggregate event count.

static constexpr uint64_t	kMaxAggregatePayloadBytes = 128ull * 1024 * 1024
	Maximum aggregate SysEx and meta payload bytes.

static constexpr uint64_t	kMaxTrackChunkBytes = 128ull * 1024 * 1024
	Maximum bytes in one track or skipped alien chunk.

Detailed Description

Transactional, resource-bounded SMF parser and authoring API.

A failed read closes the logical file and leaves the object empty. Failed authoring operations leave the existing document unchanged. write() validates and serializes the complete document before opening its target.

Threading: owner-managed offline use. tracks() returns an owner-thread reference view; no thread may read that view while another thread accesses the same MidiFile instance mutably.

Definition at line 94 of file MidiFile.h.

Member Function Documentation

◆ addChannelEvent()

bool dspark::MidiFile::addChannelEvent	(	size_t	track,
		uint32_t	delta,
		uint8_t	status,
		uint8_t	data1,
		uint8_t	data2 = `0`
	)

inline

Adds a validated MIDI channel event.

Status must be 0x80..0xef. Program-change and channel-pressure events use one data byte and require data2 == 0; all other channel events use two 7-bit data bytes.

Definition at line 163 of file MidiFile.h.

◆ addMetaEvent()

bool dspark::MidiFile::addMetaEvent	(	size_t	track,
		uint32_t	delta,
		uint8_t	type,
		std::span< const uint8_t >	payload = `{}`
	)

inline

Adds an opaque meta event.

Definition at line 197 of file MidiFile.h.

◆ addSysExEvent()

bool dspark::MidiFile::addSysExEvent	(	size_t	track,
		uint32_t	delta,
		MidiEventKind	f0OrF7,
		std::span< const uint8_t >	payload
	)

inline

Adds an F0 or F7 SysEx packet event.

Parameters

track	Destination track index.
delta	Delta time in ticks from the preceding event.
f0OrF7	Must be MidiEventKind::SysExF0 or SysExF7.
payload	SysEx payload bytes, excluding the status byte.

Definition at line 183 of file MidiFile.h.

◆ addTrack()

std::optional< size_t > dspark::MidiFile::addTrack ( )

inline

Adds an empty track to a format 1 document.

Returns: The new track index, or nullopt when the operation is invalid.

Definition at line 139 of file MidiFile.h.

◆ clear()

void dspark::MidiFile::clear ( )

inlinenoexcept

Restores the empty-state sentinel.

Definition at line 212 of file MidiFile.h.

◆ create()

bool dspark::MidiFile::create	(	uint16_t	format,
		uint16_t	ppqn,
		size_t	trackCount = `1`
	)

inline

Replaces the document with an empty writable format 0 or 1 file.

Parameters

format	SMF format, either 0 or 1.
ppqn	Ticks per quarter note in the range 1..32767.
trackCount	Initial track count. Format 0 requires exactly one.

Returns: True on success; false leaves the current document unchanged.

Definition at line 115 of file MidiFile.h.

◆ format()

int dspark::MidiFile::format ( ) const

inlinenoexcept

Returns 0, 1, or 2; returns -1 for an empty object.

Definition at line 341 of file MidiFile.h.

◆ read()

bool dspark::MidiFile::read ( const std::filesystem::path & path )

inline

Reads and validates an SMF format 0, 1, or 2 file.

Returns: True on success. Any failure leaves this object empty.

Definition at line 225 of file MidiFile.h.

◆ tempoMap()

std::optional< std::vector< MidiTempoChange > > dspark::MidiFile::tempoMap ( size_t track = 0 ) const

inline

Builds the effective tempo map for a track.

Formats 0 and 1 always use track zero. Format 2 uses the requested independent track. The returned map always starts at tick zero with the default 500000 us/qn unless a tick-zero tempo replaces it.

Definition at line 367 of file MidiFile.h.

◆ ticksPerQuarter()

uint16_t dspark::MidiFile::ticksPerQuarter ( ) const

inlinenoexcept

Returns PPQN, or zero for an empty object.

Definition at line 344 of file MidiFile.h.

◆ tickToMicroseconds()

std::optional< uint64_t > dspark::MidiFile::tickToMicroseconds	(	uint64_t	tick,
		size_t	track = `0`
	)		const

inlinenoexcept

Converts an absolute tick to floor(exact elapsed microseconds).

Returns: nullopt for an empty/invalid track or uint64 overflow.

Definition at line 397 of file MidiFile.h.

◆ tickToSeconds()

std::optional< double > dspark::MidiFile::tickToSeconds	(	uint64_t	tick,
		size_t	track = `0`
	)		const

inlinenoexcept

Converts an absolute tick directly from the shared rational sum.

Returns: nullopt for an empty/invalid track or elapsed-time overflow.

Definition at line 411 of file MidiFile.h.

◆ tracks()

const std::vector< MidiTrack > & dspark::MidiFile::tracks ( ) const

inlinenoexcept

Returns immutable semantic tracks as an owner-thread reference view.

The reference is valid only while this MidiFile remains alive and until the next non-const operation that can replace or mutate its document. No thread may read the view while another thread accesses this instance mutably. This accessor does not provide atomic publication.

Definition at line 354 of file MidiFile.h.

◆ write()

bool dspark::MidiFile::write ( const std::filesystem::path & path ) const

inline

Writes a validated format 0 or 1 document.

A missing EOT is emitted with delta zero without changing tracks(). The complete output is built before the destination is opened.

Definition at line 260 of file MidiFile.h.

Member Data Documentation

◆ kMaxAggregatePayloadBytes

constexpr uint64_t dspark::MidiFile::kMaxAggregatePayloadBytes = 128ull * 1024 * 1024

staticconstexpr

Maximum aggregate SysEx and meta payload bytes.

Definition at line 104 of file MidiFile.h.

◆ kMaxEvents

constexpr uint64_t dspark::MidiFile::kMaxEvents = 2000000

staticconstexpr

Maximum aggregate event count.

Definition at line 102 of file MidiFile.h.

◆ kMaxInputBytes

constexpr uint64_t dspark::MidiFile::kMaxInputBytes = 256ull * 1024 * 1024

staticconstexpr

Maximum accepted or produced file size.

Definition at line 98 of file MidiFile.h.

◆ kMaxTrackChunkBytes

constexpr uint64_t dspark::MidiFile::kMaxTrackChunkBytes = 128ull * 1024 * 1024

staticconstexpr

Maximum bytes in one track or skipped alien chunk.

Definition at line 106 of file MidiFile.h.

◆ kMaxTracks

constexpr uint32_t dspark::MidiFile::kMaxTracks = 4096

staticconstexpr

Maximum number of track chunks.

Definition at line 100 of file MidiFile.h.

The documentation for this class was generated from the following file:

MidiFile.h

Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ addChannelEvent()

◆ addMetaEvent()

◆ addSysExEvent()

◆ addTrack()

◆ clear()

◆ create()

◆ format()

◆ read()

◆ tempoMap()

◆ ticksPerQuarter()

◆ tickToMicroseconds()

◆ tickToSeconds()

◆ tracks()

◆ write()

Member Data Documentation

◆ kMaxAggregatePayloadBytes

◆ kMaxEvents

◆ kMaxInputBytes

◆ kMaxTrackChunkBytes

◆ kMaxTracks