clip.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/runtime/result.hpp>
#include <pulp/timebase/rational_time.hpp>
#include <pulp/timebase/tick.hpp>
#include <pulp/timeline/assets.hpp>
#include <pulp/timeline/item_id.hpp>
#include <pulp/timeline/midi_lane.hpp>
#include <pulp/timeline/note_modifier.hpp>
 
#include <compare>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <utility>
#include <variant>
#include <vector>
 
namespace pulp::timeline {

 
class SchemaRegistry;

enum class ModelErrorCode : std::uint8_t {
    InvalidItemId,
    DuplicateItemId,
    ItemIdExhausted,
    InvalidDuration,
    InvalidMediaRange,
    InvalidSampleRate,
    InvalidNote,
    OverlappingClips,
    MissingAsset,
    MissingRootSequence,
    NextItemIdNotMonotonic,
    MixedTimeAnchors,
    IncompatibleSampleRate,
    MissingItem,
    IdentityConflict,
    InvalidIdentityTransition,
    InvalidSchemaIdentity,
    InvalidContentHash,
    InvalidAssetLocator,
    DuplicateAssetRepresentation,
    InvalidOpaqueContent,
    OpaqueContentLimitExceeded,
    OpaqueContentCannotRemap,
    InvalidClipPlaybackProperties,
    MissingAutomationTarget,
    DuplicateAutomationTarget,
    InvalidTake,
    DuplicateTake,
    ActiveTakeLaneRemoval,
    InvalidTakeComp,
    OverlappingTakeComp,
    ActiveCompTakeRemoval,
    InvalidAudioLoopInfo,
    InvalidAssetStoragePolicy,
    InvalidMarker,
    InvalidRegion,
    InvalidSessionStart,
    InvalidChordScaleEvent,
    UnorderedChordScaleLane,
    InvalidDynamicsEvent,
    UnorderedDynamicsLane,
    InvalidGrooveTemplate,
    InvalidNoteModifier,
    InvalidMidiLane,
    DuplicateMidiLaneAddress,
    MissingSequenceReference,
    SequenceReferenceCycle,
    SequenceNestingTooDeep,
    InvalidTrackMixer,
    InvalidTimeConform,
    InvalidTuningReference,
    InvalidModulator,
    InvalidMacroControl,
    InvalidModulationRoute,
    MissingModulationSource,
    MissingModulationTarget,
};

struct ModelError {
    ModelErrorCode code = ModelErrorCode::InvalidItemId;
    ItemId item;
    ItemId related_item;
};

struct SchemaIdentity {
    std::string type_name;
    std::uint32_t version = 0;

    bool valid() const noexcept;
    auto operator<=>(const SchemaIdentity&) const = default;
};

class ItemIdAllocator {
  public:
    explicit constexpr ItemIdAllocator(std::uint64_t next = 1) noexcept : next_(next) {}

    runtime::Result<ItemId, ModelError> allocate() noexcept;
    constexpr std::uint64_t next_value() const noexcept {
        return next_;
    }
 
  private:
    std::uint64_t next_ = 1;
};

struct EmptyContent {};

struct MediaAsset {
    ItemId id;
    std::string name;
    std::uint64_t frame_count = 0;
    timebase::RationalRate sample_rate;
    ContentHash content_hash;
    AssetStoragePolicy storage_policy = AssetStoragePolicy::External;
    std::vector<AssetLocator> locators;
    std::vector<AssetRepresentation> representations;
    std::optional<AudioLoopInfo> loop_info;
};

struct MediaRef {
    ItemId asset_id;
    timebase::SamplePosition source_start;
    std::uint64_t frame_count = 0;
};

struct SequenceRef {
    ItemId sequence_id;
    timebase::TickPosition source_start{0};
 
    constexpr auto operator<=>(const SequenceRef&) const = default;
};

enum class ClipTimeAnchor : std::uint8_t { Musical, Absolute };

enum class TimeConform : std::uint8_t {
    None,
    Resample,
    Stretch,
};

struct MusicalTimeRange {
    timebase::TickPosition start;
    timebase::TickDuration duration;
};

struct AbsoluteTimeRange {
    timebase::SamplePosition start;
    std::uint64_t sample_count = 0;
    timebase::RationalRate sample_rate;
};

struct AbsoluteTimelineDuration {
    std::uint64_t sample_count = 0;
    timebase::RationalRate sample_rate;
};

enum class ClipFadeShape : std::uint8_t { Linear, EqualPower };

struct ClipPlaybackProperties {
    float gain_linear = 1.0f;
    std::uint64_t fade_in_duration = 0;
    std::uint64_t fade_out_duration = 0;
    ClipFadeShape fade_shape = ClipFadeShape::Linear;
    constexpr auto operator<=>(const ClipPlaybackProperties&) const = default;
};

using ClipTimeRange = std::variant<MusicalTimeRange, AbsoluteTimeRange>;

struct NoteEvent {
    ItemId id;
    timebase::TickPosition start;
    timebase::TickDuration duration;
    std::uint16_t velocity = 0xffff;
    std::uint8_t pitch = 60;
    std::uint8_t channel = 0;
};

class MidiContent {
  public:
    static runtime::Result<MidiContent, ModelError> create(std::vector<NoteEvent> notes);
    static runtime::Result<MidiContent, ModelError> create(std::vector<NoteEvent> notes,
                                                           std::vector<NoteModifier> modifiers,
                                                           std::uint64_t modifier_seed);
    static runtime::Result<MidiContent, ModelError> create(std::vector<NoteEvent> notes,
                                                           std::vector<NoteModifier> modifiers,
                                                           std::uint64_t modifier_seed,
                                                           std::vector<MidiExpressionLane> lanes);
    runtime::Result<MidiContent, ModelError> replace_note(NoteEvent note) const;

    std::span<const NoteEvent> notes() const noexcept {
        return data_->notes;
    }

    std::span<const NoteModifier> modifiers() const noexcept {
        return data_->modifiers;
    }

    std::uint64_t modifier_seed() const noexcept {
        return data_->modifier_seed;
    }

    std::span<const MidiExpressionLane> lanes() const noexcept {
        return data_->lanes;
    }

    const MidiExpressionLane* lane_for(const MidiLaneAddress& address) const noexcept;

    const NoteModifier* modifier_for(ItemId note_id) const noexcept;
 
  private:
    struct Data {
        std::vector<NoteEvent> notes;
        std::vector<NoteModifier> modifiers;
        std::uint64_t modifier_seed = 0;
        std::vector<MidiExpressionLane> lanes;
    };
 
    explicit MidiContent(std::shared_ptr<const Data> data) : data_(std::move(data)) {}
 
    std::shared_ptr<const Data> data_;
};

class RegisteredContent {
  public:
    const SchemaIdentity& schema() const noexcept {
        return schema_;
    }

    const std::shared_ptr<const void>& value() const noexcept {
        return value_;
    }

    const std::string& canonical_payload_json() const noexcept {
        return canonical_payload_json_;
    }

    std::size_t retained_bytes() const noexcept {
        return retained_bytes_;
    }

    const std::shared_ptr<const void>& schema_registry_identity() const noexcept {
        return schema_registry_identity_;
    }

    template <typename T> const T* value_as() const noexcept {
        return static_cast<const T*>(value_.get());
    }
 
  private:
    friend class SchemaRegistry;
    RegisteredContent(SchemaIdentity schema, std::shared_ptr<const void> value,
                      std::string canonical_payload_json, std::size_t retained_bytes,
                      std::shared_ptr<const void> schema_registry_identity)
        : schema_(std::move(schema)), value_(std::move(value)),
          canonical_payload_json_(std::move(canonical_payload_json)),
          retained_bytes_(retained_bytes),
          schema_registry_identity_(std::move(schema_registry_identity)) {}
    SchemaIdentity schema_;
    std::shared_ptr<const void> value_;
    std::string canonical_payload_json_;
    std::size_t retained_bytes_ = 0;
    std::shared_ptr<const void> schema_registry_identity_;
};

struct OpaqueContentLimits {
    std::size_t max_input_bytes = 1024ull * 1024ull * 1024ull;
    std::size_t max_depth = 64;
    std::size_t max_total_values = 30'000'000;
    std::size_t max_array_elements = 10'000'000;
    std::size_t max_object_members = 4'096;
    std::size_t max_string_bytes = 16ull * 1024ull * 1024ull;
    std::size_t max_opaque_bytes = 64ull * 1024ull * 1024ull;
 
    constexpr auto operator<=>(const OpaqueContentLimits&) const = default;
};

class OpaqueContent {
  public:
    static runtime::Result<OpaqueContent, ModelError>
    create(SchemaIdentity schema, std::string raw_json, OpaqueContentLimits limits = {});

    const SchemaIdentity& schema() const noexcept {
        return schema_;
    }

    const std::string& raw_json() const noexcept {
        return raw_json_;
    }

    const OpaqueContentLimits& validation_limits() const noexcept {
        return limits_;
    }
 
  private:
    OpaqueContent(SchemaIdentity schema, std::string raw_json, OpaqueContentLimits limits)
        : schema_(std::move(schema)), raw_json_(std::move(raw_json)), limits_(limits) {}
    SchemaIdentity schema_;
    std::string raw_json_;
    OpaqueContentLimits limits_;
};

using ClipContent = std::variant<EmptyContent, MediaRef, MidiContent, RegisteredContent,
                                 OpaqueContent, SequenceRef>;

template <class... Fs> struct ClipContentCases : Fs... {
    using Fs::operator()...;
};
template <class... Fs> ClipContentCases(Fs...) -> ClipContentCases<Fs...>;

inline constexpr std::size_t kClipContentAlternativeCount = std::variant_size_v<ClipContent>;

class Clip {
  public:
    static runtime::Result<Clip, ModelError> create(ItemId id, timebase::TickPosition start,
                                                    timebase::TickDuration duration,
                                                    ClipContent content,
                                                    ClipPlaybackProperties playback = {},
                                                    TimeConform time_conform = TimeConform::None);
    static runtime::Result<Clip, ModelError>
    create_absolute(ItemId id, timebase::SamplePosition start, std::uint64_t sample_count,
                    timebase::RationalRate sample_rate, ClipContent content,
                    ClipPlaybackProperties playback = {},
                    TimeConform time_conform = TimeConform::None);

    ItemId id() const noexcept;
    ClipTimeAnchor time_anchor() const noexcept;
    const ClipTimeRange& time_range() const noexcept;
    timebase::TickPosition start() const noexcept;
    timebase::TickDuration duration() const noexcept;
    timebase::TickPosition end() const noexcept;
    timebase::SamplePosition absolute_start() const noexcept;
    std::uint64_t absolute_duration_samples() const noexcept;
    timebase::RationalRate absolute_sample_rate() const noexcept;
    timebase::SamplePosition absolute_end() const noexcept;
    const ClipContent& content() const noexcept;
    runtime::Result<Clip, ModelError> with_time_range(ClipTimeRange range) const;
    runtime::Result<Clip, ModelError> with_content(ClipContent content) const;
    runtime::Result<Clip, ModelError>
    with_playback_properties(ClipPlaybackProperties playback) const;
    runtime::Result<Clip, ModelError> with_time_conform(TimeConform time_conform) const;
    ClipPlaybackProperties playback_properties() const noexcept;
    TimeConform time_conform() const noexcept;
 
  private:
    struct Data;
    explicit Clip(std::shared_ptr<const Data> data) : data_(std::move(data)) {}
    std::shared_ptr<const Data> data_;
};

 
} // namespace pulp::timeline