smf.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/runtime/result.hpp>
#include <pulp/timeline/model.hpp>
 
#include <cstddef>
#include <cstdint>
#include <span>
#include <string>
#include <vector>
 
namespace pulp::timeline {
 
// Import and export of Standard MIDI Files (SMF, RP-001) against the project's
// tempo and meter maps.
//
// An SMF carries its own musical timebase: a header division in ticks per
// quarter note, plus Set Tempo and Time Signature meta-events that place tempo
// and meter changes on that grid. Conversion therefore stays entirely in the
// musical domain — SMF ticks scale to canonical timebase::kTicksPerQuarter
// ticks, and the file's tempo/meter meta-events become the Project's TempoMap
// and MeterMap. No seconds-domain flattening is involved in either direction,
// so a tempo change mid-file survives the round trip as a tempo point rather
// than as pre-multiplied wall-clock positions.
//
// Tick exactness. `canonical = round(smf_tick * kTicksPerQuarter / division)`
// is exact for every tick when `kTicksPerQuarter % division == 0` (true for
// 96, 120, 192, 240, 480, 960, and every other divisor of 705600; false for
// 384 and 1920). Otherwise the conversion rounds half away from zero and the
// error is bounded by 0.5 canonical ticks; SmfImport reports both facts.
// Export is exact by default: a canonical tick that the requested division
// cannot represent is an error unless `allow_lossy_tick_rounding` is set.
//
// Documented import subset (everything outside it fails closed):
//   * MThd format 0 or 1; a metrical (non-SMPTE) division
//   * MTrk chunks only, exactly the count the header declares, no trailing bytes
//   * Note On (0x9n) and Note Off (0x8n); a Note On with velocity 0 is a
//     Note Off, per the specification
//   * Meta events Set Tempo (0x51), Time Signature (0x58),
//     Sequence/Track Name (0x03), and End of Track (0x2F)
// Any other channel message, system-exclusive block, or meta event is rejected
// unless the caller explicitly opts into SmfUnsupportedEventPolicy::IgnoreNonNote.
//
// Fields carried by supported events that have no timeline counterpart are
// documented rather than silently reinterpreted: the Time Signature event's
// metronome hints (MIDI clocks per click, 32nd notes per quarter) are not
// retained, and export writes the conventional 24/8.
//
// Export covers note content plus the tempo and meter maps. Device chains,
// automation lanes, takes, freezes, and media assets have no SMF
// representation and are outside the format's scope. Per-note probability,
// conditions, and ratchets are playback semantics rather than fixed MIDI
// events, so exporting a clip that authors them fails with UnsupportedFeature.


enum class SmfErrorCode : std::uint8_t {
    Truncated,             
    MissingHeader,         
    InvalidHeader,         
    UnsupportedFormat,     
    UnsupportedDivision,   
    UnsupportedFeature,    
    MalformedEvent,        
    UnbalancedNote,        
    InvalidValue,          
    InexactTickConversion, 
    TickRangeExceeded,     
    LimitExceeded,         
    TempoMapRejected,      
    MeterMapRejected,      
    ModelRejected,         
};

struct SmfError {
    SmfErrorCode code = SmfErrorCode::MissingHeader;
    std::string message;
    ModelError model_error{};
};

enum class SmfUnsupportedEventPolicy : std::uint8_t {
    Reject,
    IgnoreNonNote,
};

struct SmfImportLimits {
    std::size_t max_file_bytes = 64u * 1024u * 1024u;
    std::size_t max_tracks = 4'096;
    std::size_t max_events = 5'000'000;
    std::size_t max_notes = 5'000'000;
    std::size_t max_concurrent_notes = 65'536;
    std::size_t max_tempo_points = 65'536;
    std::size_t max_meter_points = 65'536;
    std::size_t max_payload_bytes = 1u * 1024u * 1024u;
    std::size_t max_track_name_bytes = 4'096;
    std::int64_t max_smf_ticks = std::int64_t{1} << 34;
};

struct SmfImportOptions {
    SmfImportLimits limits{};
    SmfUnsupportedEventPolicy unsupported_events = SmfUnsupportedEventPolicy::Reject;
};

struct SmfImport {
    Project project;
    std::uint16_t division = 0;
    bool exact_tick_conversion = true;
    std::int64_t max_tick_rounding_error = 0;
};

runtime::Result<SmfImport, SmfError> import_smf(std::span<const std::uint8_t> file_bytes);

runtime::Result<SmfImport, SmfError> import_smf(std::span<const std::uint8_t> file_bytes,
                                                const SmfImportOptions& options);

struct SmfExportOptions {
    std::uint16_t ticks_per_quarter = 960;
    bool allow_lossy_tick_rounding = false;
    bool skip_non_note_clips = false;
    std::size_t max_events = 5'000'000;
};

struct SmfExport {
    std::vector<std::uint8_t> bytes;
    bool exact_tick_conversion = true;
    std::int64_t max_tick_rounding_error = 0;
};

runtime::Result<SmfExport, SmfError> export_smf(const Project& project);

runtime::Result<SmfExport, SmfError> export_smf(const Project& project,
                                                const SmfExportOptions& options);

 
} // namespace pulp::timeline