Explicit import and export boundaries for external formats. More...

Files
file	dawproject_import.hpp
	Bounded import of the documented DAWproject arrangement subset.
file	smf.hpp
	Bounded import and export of the documented Standard MIDI File subset.

Namespaces
namespace	pulp::timeline::detail

Classes
struct	pulp::timeline::DawProjectImportError
	Diagnostic returned when an import rejects the whole document. More...
struct	pulp::timeline::DawProjectImportLimits
	Hard resource ceilings for one import. More...
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...

Typedefs
using	pulp::timeline::DawProjectMediaResolver
	Resolves a safe package-relative path to complete media bytes.

Enumerations
enum class	pulp::timeline::DawProjectImportErrorCode : std::uint8_t { pulp::timeline::DawProjectImportErrorCode::ParseError , pulp::timeline::DawProjectImportErrorCode::MissingRoot , pulp::timeline::DawProjectImportErrorCode::UnsupportedVersion , pulp::timeline::DawProjectImportErrorCode::UnsupportedFeature , pulp::timeline::DawProjectImportErrorCode::MissingAttribute , pulp::timeline::DawProjectImportErrorCode::InvalidValue , pulp::timeline::DawProjectImportErrorCode::MissingMediaBytes , pulp::timeline::DawProjectImportErrorCode::DuplicateTrackId , pulp::timeline::DawProjectImportErrorCode::DanglingTrackReference , pulp::timeline::DawProjectImportErrorCode::ModelRejected , pulp::timeline::DawProjectImportErrorCode::LimitExceeded }
	Stable category for a DAWproject import failure. More...
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< Project, DawProjectImportError >	pulp::timeline::import_dawproject_xml (std::string_view project_xml)
	Parses a DAWproject project.xml document without resolving audio media.
runtime::Result< Project, DawProjectImportError >	pulp::timeline::import_dawproject_xml (std::string_view project_xml, DawProjectMediaResolver media_resolver)
	Parses a DAWproject project.xml document using media_resolver.
runtime::Result< Project, DawProjectImportError >	pulp::timeline::import_dawproject_xml (std::string_view project_xml, DawProjectMediaResolver media_resolver, const DawProjectImportLimits &limits)
	Parses a DAWproject project.xml document under explicit resource limits.
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

Explicit import and export boundaries for external formats.

Typedef Documentation

◆ DawProjectMediaResolver

using pulp::timeline::DawProjectMediaResolver

Initial value:

std::function<std::optional<std::vector<std::uint8_t>>(std::string_view package_path)>

Resolves a safe package-relative path to complete media bytes.

The callback runs synchronously on the importing thread and owns its return allocation. Returning null reports missing media. The importer hashes and retains successful bytes only within the configured limits.

Enumeration Type Documentation

◆ DawProjectImportErrorCode

enum class pulp::timeline::DawProjectImportErrorCode : std::uint8_t

strong

Stable category for a DAWproject import failure.

Enumerator
ParseError	The XML text is not well-formed.
MissingRoot	No Project document element exists.
UnsupportedVersion	The Project major version is unsupported.
UnsupportedFeature	A construct lies outside the accepted subset.
MissingAttribute	A required attribute is absent.
InvalidValue	An attribute is unparseable or out of range.
MissingMediaBytes	The resolver did not supply referenced media.
DuplicateTrackId	Two Track elements share an identity.
DanglingTrackReference	An arrangement lane names an unknown track.
ModelRejected	The assembled Project violates a model invariant.
LimitExceeded	A configured import resource limit was exceeded.

◆ SmfErrorCode

enum class pulp::timeline::SmfErrorCode : std::uint8_t

strong

Stable category for an SMF import or export failure.

Enumerator
Truncated	Input ended inside a chunk, event, or payload.
MissingHeader	No MThd chunk starts the input.
InvalidHeader	The MThd contents are unusable.
UnsupportedFormat	The file uses independent-sequence format 2.
UnsupportedDivision	The division is SMPTE-based or zero.
UnsupportedFeature	A construct lies outside the accepted subset.
MalformedEvent	Running status, variable length, or meta length is invalid.
UnbalancedNote	A note-on/off pair is incomplete.
InvalidValue	A value is outside its representable range.
InexactTickConversion	A requested export tick is not exactly representable.
TickRangeExceeded	A tick exceeds the SMF or canonical domain.
LimitExceeded	A configured resource limit was exceeded.
TempoMapRejected	The assembled tempo map is invalid.
MeterMapRejected	The assembled meter map is invalid.
ModelRejected	The assembled Project violates a model invariant.

◆ SmfUnsupportedEventPolicy

enum class pulp::timeline::SmfUnsupportedEventPolicy : std::uint8_t

strong

Policy for a well-formed event outside the documented import subset.

Enumerator
Reject	Reject the file so an unhandled event is never silently dropped.
IgnoreNonNote	Discard well-formed non-note channel, system-exclusive, and meta events.

Function Documentation

◆ export_smf() [1/2]

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.

Parameters

project Immutable source project.

Returns: Encoded bytes and fidelity metadata, or a structured error.

◆ export_smf() [2/2]

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.

Track 0 carries tempo and meter maps; each Timeline track with note content follows as its own MTrk. A note velocity that scales to MIDI zero is rejected because zero-velocity Note On means Note Off. Running status is not emitted.

Parameters

project	Immutable source project.
options	Tick-grid, loss, and resource policy.

Returns: Encoded bytes and fidelity metadata, or a structured error.

◆ import_dawproject_xml() [1/3]

runtime::Result< Project, DawProjectImportError > pulp::timeline::import_dawproject_xml ( std::string_view project_xml )

Parses a DAWproject project.xml document without resolving audio media.

Audio references are rejected because their durable content identities cannot be established. The default resource limits apply.

Parameters

project_xml Complete project.xml UTF-8 text, borrowed for the call.

Returns: An atomically assembled Project or a structured import error.

◆ import_dawproject_xml() [2/3]

runtime::Result< Project, DawProjectImportError > pulp::timeline::import_dawproject_xml	(	std::string_view	project_xml,
		DawProjectMediaResolver	media_resolver )

Parses a DAWproject project.xml document using media_resolver.

The default resource limits apply. The import is atomic: malformed, unsupported, unresolved, or over-limit input returns an error and no partial Project.

Parameters

project_xml	Complete project.xml UTF-8 text, borrowed for the call.
media_resolver	Synchronous resolver for package-relative media paths.

Returns: An atomically assembled Project or a structured import error.

◆ import_dawproject_xml() [3/3]

runtime::Result< Project, DawProjectImportError > pulp::timeline::import_dawproject_xml	(	std::string_view	project_xml,
		DawProjectMediaResolver	media_resolver,
		const DawProjectImportLimits &	limits )

Parses a DAWproject project.xml document under explicit resource limits.

Out-of-subset constructs and malformed input are rejected rather than partially imported. Audio projects require a resolver so their durable identities can be sealed. The resolver runs synchronously and may be invoked repeatedly for the same path.

Parameters

project_xml	Complete project.xml UTF-8 text, borrowed for the call.
media_resolver	Synchronous resolver for package-relative media paths.
limits	Hard ceilings applied throughout parsing and assembly.

Returns: An atomically assembled Project or a structured import error.

◆ import_smf() [1/2]

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.

Parameters

file_bytes Complete SMF bytes, borrowed for the call.

Returns: The imported Project and fidelity metadata, or a structured error.

◆ import_smf() [2/2]

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.

Malformed input and unsupported constructs reject the whole import. Each content-bearing MTrk becomes one Track; tempo-only conductor chunks create no empty Timeline track.

Parameters

file_bytes	Complete SMF bytes, borrowed for the call.
options	Resource and unsupported-event policy.

Returns: The imported Project and fidelity metadata, or a structured error.

Pulp 1.88.0 Cross-platform audio plugin framework

Files

Namespaces

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ DawProjectMediaResolver

Enumeration Type Documentation

◆ DawProjectImportErrorCode

◆ SmfErrorCode

◆ SmfUnsupportedEventPolicy

Function Documentation

◆ export_smf() [1/2]

◆ export_smf() [2/2]

◆ import_dawproject_xml() [1/3]

◆ import_dawproject_xml() [2/3]

◆ import_dawproject_xml() [3/3]

◆ import_smf() [1/2]

◆ import_smf() [2/2]