smf.hpp File Reference

Bounded import and export of the documented Standard MIDI File subset. More...

#include <pulp/runtime/result.hpp>
#include <pulp/timeline/model.hpp>
#include <cstddef>
#include <cstdint>
#include <span>
#include <string>
#include <vector>

Go to the source code of this file.

Classes
struct	pulp::timeline::SmfError
	Diagnostic returned when an SMF operation rejects the whole conversion. More...
struct	pulp::timeline::SmfImportLimits
	Hard resource ceilings for one SMF import. More...
struct	pulp::timeline::SmfImportOptions
	Caller-selected resource and unsupported-event policy for SMF import. More...
struct	pulp::timeline::SmfImport
	Imported immutable Project plus tick-conversion fidelity metadata. More...
struct	pulp::timeline::SmfExportOptions
	Tick-grid, loss policy, and work bound for SMF export. More...
struct	pulp::timeline::SmfExport
	Encoded SMF bytes plus tick-conversion fidelity metadata. More...

Namespaces
namespace	pulp
namespace	pulp::timeline

Enumerations
enum class	pulp::timeline::SmfErrorCode : std::uint8_t {   pulp::timeline::SmfErrorCode::Truncated , pulp::timeline::SmfErrorCode::MissingHeader , pulp::timeline::SmfErrorCode::InvalidHeader , pulp::timeline::SmfErrorCode::UnsupportedFormat ,   pulp::timeline::SmfErrorCode::UnsupportedDivision , pulp::timeline::SmfErrorCode::UnsupportedFeature , pulp::timeline::SmfErrorCode::MalformedEvent , pulp::timeline::SmfErrorCode::UnbalancedNote ,   pulp::timeline::SmfErrorCode::InvalidValue , pulp::timeline::SmfErrorCode::InexactTickConversion , pulp::timeline::SmfErrorCode::TickRangeExceeded , pulp::timeline::SmfErrorCode::LimitExceeded ,   pulp::timeline::SmfErrorCode::TempoMapRejected , pulp::timeline::SmfErrorCode::MeterMapRejected , pulp::timeline::SmfErrorCode::ModelRejected }
	Stable category for an SMF import or export failure. More...
enum class	pulp::timeline::SmfUnsupportedEventPolicy : std::uint8_t { pulp::timeline::SmfUnsupportedEventPolicy::Reject , pulp::timeline::SmfUnsupportedEventPolicy::IgnoreNonNote }
	Policy for a well-formed event outside the documented import subset. More...

Functions
runtime::Result< SmfImport, SmfError >	pulp::timeline::import_smf (std::span< const std::uint8_t > file_bytes)
	Decodes SMF bytes into a Project using default limits and strict event policy.
runtime::Result< SmfImport, SmfError >	pulp::timeline::import_smf (std::span< const std::uint8_t > file_bytes, const SmfImportOptions &options)
	Decodes SMF bytes into a Project under explicit import options.
runtime::Result< SmfExport, SmfError >	pulp::timeline::export_smf (const Project &project)
	Encodes a Project's root sequence as a format-1 SMF with strict defaults.
runtime::Result< SmfExport, SmfError >	pulp::timeline::export_smf (const Project &project, const SmfExportOptions &options)
	Encodes a Project's root sequence as a format-1 SMF under explicit options.

Detailed Description

Bounded import and export of the documented Standard MIDI File subset.

An SMF carries its own musical timebase: a metrical header division plus tempo and time-signature events. Conversion stays in the musical domain; no seconds-domain flattening occurs.

Import accepts format 0 or 1, a metrical division, Note On/Off, Set Tempo, Time Signature, Sequence/Track Name, and End of Track. Other well-formed events require an explicit IgnoreNonNote policy. Export covers note content plus tempo and meter maps; other Timeline content lies outside the format.

Tick conversion is exact when the file division divides timebase::kTicksPerQuarter. Import reports rounding when it does not. Export rejects inexact ticks unless allow_lossy_tick_rounding is explicitly set.