Pulp 1.88.0
Cross-platform audio plugin framework
Loading...
Searching...
No Matches
pulp::interchange Namespace Reference

Namespaces

namespace  detail

Classes

struct  CensusLimits
 Bounds on how much evidence one census retains. More...
class  ConceptCensus
 Which interchange concepts a document uses, how often, and where. More...
struct  ExportArtifact
 What one export produced. More...
struct  ExportArtifacts
struct  ExportError
struct  ExportOptions
class  ExportPlan
 A document measured against one format's capability table: what survives, and what it costs. More...
class  FormatBoundExportWriter
 A format-bound byte writer that can only be invoked by run_export. More...
struct  ImportRow
struct  ExportRow
struct  LossEntry
 One concept a document uses that an export cannot carry intact. More...
class  LossManifest
 Everything one export costs the document. More...

Typedefs

using ExportWriter
 The released v0.759 writer seam.

Enumerations

enum class  ExportErrorCode : std::uint8_t { UnacceptedLoss , NoWriterRegistered , WriterFailed , WriterFormatMismatch }
enum class  ImportLevel : std::uint8_t { None = 0 , PreserveOpaque = 1 , Partial = 2 , Full = 3 }
 How much of a concept a format's reader admits. More...
enum class  ExportLevel : std::uint8_t { Drop = 0 , RoundtripOnly = 1 , Degrade = 2 , Full = 3 }
 What a format's writer does with a concept the document uses. More...
enum class  LossClass : std::uint8_t { Dropped = 0 , Degraded = 1 , Flattened = 2 , Approximated = 3 }
 How a concept is lost when a format cannot carry it intact. More...
enum class  Format : std::uint8_t { DawProject = 0 , Smf = 1 }
 Interchange formats with a committed capability declaration. More...
enum class  Concept : std::uint16_t {
  Unknown = 0 , TrackFlat = 1 , TrackGroup = 2 , TrackVideo = 3 ,
  ClipMusical = 4 , ClipAbsolute = 5 , ClipNote = 6 , ClipMedia = 7 ,
  ClipGain = 8 , ClipFades = 9 , ClipCrossfade = 10 , ClipWarp = 11 ,
  ClipLaunch = 12 , GapExplicit = 13 , TempoSingle = 14 , TempoMap = 15 ,
  MeterSingle = 16 , MeterMap = 17 , Marker = 18 , TimecodeOrigin = 19 ,
  MediaProvenance = 20 , MixerTrackGain = 21 , MixerTrackPan = 22 , MixerSends = 23 ,
  AutomationDeviceParam = 24 , AutomationTrackGain = 25 , AutomationTrackPan = 26 , DevicePlacement = 27 ,
  DevicePayload = 28 , EffectTimewarp = 29 , TakeLane = 30 , TakeComp = 31 ,
  TrackFreeze = 32 , AssetSealedHash = 33 , AssetEmbeddedMedia = 34 , AssetReferencedMedia = 35 ,
  SequenceMultiple = 36 , SequenceNested = 37 , ContentRegistered = 38 , ContentOpaque = 39 ,
  EditRateNonAudio = 40 , ContextChordScale = 41 , ContextGroove = 42 , ClipNoteModifier = 43 ,
  ClipEmpty = 44 , TempoRamp = 45 , ClipNoteVelocityQuantized = 46 , TempoValueQuantized = 47 ,
  ClipMediaWindow = 48 , ClipFadeShape = 49 , ClipMidiExpressionLane = 50 , SequenceSectionRole = 51 ,
  ContextChordBass = 52 , ContextChordExtension = 53 , ContextChordVoicing = 54 , TuningProject = 55 ,
  TuningInstrument = 56 , ModulationModulator = 57 , ModulationMacro = 58 , ModulationRouteDeviceParam = 59 ,
  ModulationRouteTrackMixer = 60
}
 The format-neutral interchange concept vocabulary. More...

Functions

ConceptCensus census (const timeline::Project &project, const CensusLimits &limits={})
 Walk a document and record every concept it uses.
ExportPlan plan_export (const timeline::Project &project, Format format, const CensusLimits &limits={})
 Measure a document against a format.
std::string loss_manifest_json (const ExportPlan &plan)
 Serialize the canonical loss manifest carried by every plan and export result.
runtime::Result< ExportArtifacts, ExportError > run_export (const ExportPlan &plan, const ExportOptions &options, const ExportWriter &writer)
 Execute a plan.
runtime::Result< ExportArtifacts, ExportError > run_export (const ExportPlan &plan, const ExportOptions &options, const FormatBoundExportWriter &writer)
 Execute through a format-bound writer.
constexpr std::string_view format_id (Format format) noexcept
 The format's stable string id.
constexpr std::string_view format_display_name (Format format) noexcept
 The format's human-facing name.
constexpr bool format_has_writer (Format format) noexcept
 Whether a writer exists for this format. run_export refuses without one.
constexpr bool format_from_id (std::string_view id, Format &out) noexcept
 Resolve a string id to its format. Returns false when unrecognized.
constexpr const ImportRow & import_capability (Format format, Concept concept_value) noexcept
 The format's import declaration for one concept.
constexpr const ExportRow & export_capability (Format format, Concept concept_value) noexcept
 The format's export declaration for one concept, generated the same way (omitted concepts become Drop, so they surface as a loss needing consent).
constexpr bool import_supports (Format format, Concept concept_value) noexcept
 Whether the format's reader may admit the concept at all.
constexpr bool export_is_lossless (Format format, Concept concept_value) noexcept
 Whether exporting the concept costs the document anything.
constexpr std::string_view concept_id (Concept concept_value) noexcept
 The concept's stable string id, as written in the capability JSON.
constexpr std::string_view concept_summary (Concept concept_value) noexcept
 One-line description of what the concept covers.
constexpr bool concept_detectable_in_model (Concept concept_value) noexcept
 Whether a census over a timeline Project can observe this concept.
constexpr Concept concept_from_id (std::string_view id) noexcept
 Resolve a string id to its concept.
constexpr std::string_view export_level_id (ExportLevel level) noexcept
 Stable id for the lossy export level written into manifests.
constexpr std::string_view loss_class_id (LossClass loss_class) noexcept
 Stable id for a loss class, for manifests written into an artifact.

Variables

constexpr std::size_t kFormatCount = 2
constexpr std::size_t kConceptCount = 61

Typedef Documentation

◆ ExportWriter

Initial value:
std::function<runtime::Result<ExportArtifacts, ExportError>(const ExportPlan&)>
A document measured against one format's capability table: what survives, and what it costs.
Definition export_plan.hpp:68

The released v0.759 writer seam.

Kept source-compatible so existing SDK consumers can still construct, store, and invoke their std::function.

Enumeration Type Documentation

◆ Concept

enum class pulp::interchange::Concept : std::uint16_t
strong

The format-neutral interchange concept vocabulary.

Append-only: committed format tables are written against these names.

Enumerator
Unknown 
TrackFlat 
TrackGroup 
TrackVideo 
ClipMusical 
ClipAbsolute 
ClipNote 
ClipMedia 
ClipGain 
ClipFades 
ClipCrossfade 
ClipWarp 
ClipLaunch 
GapExplicit 
TempoSingle 
TempoMap 
MeterSingle 
MeterMap 
Marker 
TimecodeOrigin 
MediaProvenance 
MixerTrackGain 
MixerTrackPan 
MixerSends 
AutomationDeviceParam 
AutomationTrackGain 
AutomationTrackPan 
DevicePlacement 
DevicePayload 
EffectTimewarp 
TakeLane 
TakeComp 
TrackFreeze 
AssetSealedHash 
AssetEmbeddedMedia 
AssetReferencedMedia 
SequenceMultiple 
SequenceNested 
ContentRegistered 
ContentOpaque 
EditRateNonAudio 
ContextChordScale 
ContextGroove 
ClipNoteModifier 
ClipEmpty 
TempoRamp 
ClipNoteVelocityQuantized 
TempoValueQuantized 
ClipMediaWindow 
ClipFadeShape 
ClipMidiExpressionLane 
SequenceSectionRole 
ContextChordBass 
ContextChordExtension 
ContextChordVoicing 
TuningProject 
TuningInstrument 
ModulationModulator 
ModulationMacro 
ModulationRouteDeviceParam 
ModulationRouteTrackMixer 

◆ ExportErrorCode

enum class pulp::interchange::ExportErrorCode : std::uint8_t
strong
Enumerator
UnacceptedLoss 

The plan loses concepts the caller did not list in accepted_losses.

NoWriterRegistered 

No writer was supplied for the format.

WriterFailed 

The writer ran and failed on its own terms.

WriterFormatMismatch 

The supplied writer belongs to a different interchange format.

◆ ExportLevel

enum class pulp::interchange::ExportLevel : std::uint8_t
strong

What a format's writer does with a concept the document uses.

Enumerator
Drop 
RoundtripOnly 
Degrade 
Full 

◆ Format

enum class pulp::interchange::Format : std::uint8_t
strong

Interchange formats with a committed capability declaration.

Enumerator
DawProject 
Smf 

◆ ImportLevel

enum class pulp::interchange::ImportLevel : std::uint8_t
strong

How much of a concept a format's reader admits.

Enumerator
None 
PreserveOpaque 
Partial 
Full 

◆ LossClass

enum class pulp::interchange::LossClass : std::uint8_t
strong

How a concept is lost when a format cannot carry it intact.

Enumerator
Dropped 
Degraded 
Flattened 
Approximated 

Function Documentation

◆ census()

ConceptCensus pulp::interchange::census ( const timeline::Project & project,
const CensusLimits & limits = {} )

Walk a document and record every concept it uses.

Only concepts the model can express are ever recorded: concept_detectable_in_model is the generated predicate for which those are. Concepts that exist solely in some interchange format have no representation to find here and stay absent.

◆ concept_detectable_in_model()

bool pulp::interchange::concept_detectable_in_model ( Concept concept_value)
constexprnoexcept

Whether a census over a timeline Project can observe this concept.

Concepts that exist only in some interchange format are never recorded.

◆ concept_from_id()

Concept pulp::interchange::concept_from_id ( std::string_view id)
constexprnoexcept

Resolve a string id to its concept.

Unrecognized ids yield Concept::Unknown, which no format lists as importable.

◆ concept_id()

std::string_view pulp::interchange::concept_id ( Concept concept_value)
constexprnoexcept

The concept's stable string id, as written in the capability JSON.

◆ concept_summary()

std::string_view pulp::interchange::concept_summary ( Concept concept_value)
constexprnoexcept

One-line description of what the concept covers.

◆ export_capability()

const ExportRow & pulp::interchange::export_capability ( Format format,
Concept concept_value )
constexprnoexcept

The format's export declaration for one concept, generated the same way (omitted concepts become Drop, so they surface as a loss needing consent).

◆ export_is_lossless()

bool pulp::interchange::export_is_lossless ( Format format,
Concept concept_value )
constexprnoexcept

Whether exporting the concept costs the document anything.

◆ export_level_id()

std::string_view pulp::interchange::export_level_id ( ExportLevel level)
constexprnoexcept

Stable id for the lossy export level written into manifests.

◆ format_display_name()

std::string_view pulp::interchange::format_display_name ( Format format)
constexprnoexcept

The format's human-facing name.

◆ format_from_id()

bool pulp::interchange::format_from_id ( std::string_view id,
Format & out )
constexprnoexcept

Resolve a string id to its format. Returns false when unrecognized.

◆ format_has_writer()

bool pulp::interchange::format_has_writer ( Format format)
constexprnoexcept

Whether a writer exists for this format. run_export refuses without one.

◆ format_id()

std::string_view pulp::interchange::format_id ( Format format)
constexprnoexcept

The format's stable string id.

◆ import_capability()

const ImportRow & pulp::interchange::import_capability ( Format format,
Concept concept_value )
constexprnoexcept

The format's import declaration for one concept.

Every concept has a row: concepts the format's JSON omits are generated as None.

◆ import_supports()

bool pulp::interchange::import_supports ( Format format,
Concept concept_value )
constexprnoexcept

Whether the format's reader may admit the concept at all.

This is the single decision every import refusal site derives from.

◆ loss_class_id()

std::string_view pulp::interchange::loss_class_id ( LossClass loss_class)
constexprnoexcept

Stable id for a loss class, for manifests written into an artifact.

◆ loss_manifest_json()

std::string pulp::interchange::loss_manifest_json ( const ExportPlan & plan)

Serialize the canonical loss manifest carried by every plan and export result.

The exact same bytes are appended to successful export artifacts as pulp-loss-manifest.json.

◆ plan_export()

ExportPlan pulp::interchange::plan_export ( const timeline::Project & project,
Format format,
const CensusLimits & limits = {} )

Measure a document against a format.

Pure: no I/O, no writer, no failure mode – a census and a table lookup always produce an answer, and an answer that says "everything is lost" is still a plan.

◆ run_export() [1/2]

runtime::Result< ExportArtifacts, ExportError > pulp::interchange::run_export ( const ExportPlan & plan,
const ExportOptions & options,
const ExportWriter & writer )

Execute a plan.

Refuses before touching the writer when the plan loses anything the caller did not accept.

◆ run_export() [2/2]

runtime::Result< ExportArtifacts, ExportError > pulp::interchange::run_export ( const ExportPlan & plan,
const ExportOptions & options,
const FormatBoundExportWriter & writer )

Execute through a format-bound writer.

New adapters should expose this overload so a plan for one format cannot authorize another format's bytes.

Variable Documentation

◆ kConceptCount

std::size_t pulp::interchange::kConceptCount = 61
inlineconstexpr

◆ kFormatCount

std::size_t pulp::interchange::kFormatCount = 2
inlineconstexpr