flpkit 0.8.1__py3-none-any.whl

flpkit/formats/effects.py

@@ -0,0 +1,170 @@
+"""Captured mixer-effect references, spliced without interpreting plugin state."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from hashlib import sha256
+from importlib.resources import files
+
+from flpkit.codec import EVENT_MIXER_FLAGS, FlpError, SpliceSite, Stream, Target, verify_identical
+
+_INTERNAL_NAME = 201
+_WRAPPER = 212
+_STATE = 213
+_SLOT = 98
+_RESOURCE_DIR = ("data", "plugins")
+
+
+@dataclass(frozen=True)
+class PluginReference:
+    """One FL-authored opaque plugin tuple captured as data."""
+
+    name: str
+    chunk: bytes
+    fl_build: str
+    kind: str
+
+
+class PluginDatabase:
+    """Lazy captured-reference lookup, indexed by plugin name."""
+
+    def __init__(self, references: Mapping[str, PluginReference] | None = None):
+        self._references = dict(references or {})
+        self._index: dict[str, str] | None = {} if references is not None else None
+
+    def reference(self, name: str) -> PluginReference:
+        if name in self._references:
+            return self._references[name]
+        if self._index is None:
+            root = files("flpkit").joinpath(*_RESOURCE_DIR)
+            self._index = json.loads(root.joinpath("index.json").read_text())
+        filename = self._index.get(name)
+        if filename is None:
+            raise FlpError(f"no FL-authored default-state reference for effect {name!r}")
+        record = json.loads(files("flpkit").joinpath(*_RESOURCE_DIR, filename).read_text())
+        try:
+            chunk = bytes.fromhex(record["chunk_hex"])
+            reference = PluginReference(record["name"], chunk, record["fl_build"], record["kind"])
+        except (KeyError, TypeError, ValueError) as error:
+            raise FlpError(f"invalid captured plugin reference {filename!r}") from error
+        if reference.name != name or sha256(chunk).hexdigest() != record.get("sha256"):
+            raise FlpError(f"captured plugin reference {filename!r} failed its integrity check")
+        self._references[name] = reference
+        return reference
+
+
+@dataclass(frozen=True)
+class Effect:
+    """A decoded effect tuple whose plugin state remains opaque."""
+
+    name: str
+    chunk: bytes
+
+
+DEFAULT_PLUGIN_DATABASE = PluginDatabase()
+
+
+class EffectFormat:
+    """The proven empty Master slot 0 insertion, expressed as a Format."""
+
+    name = "effects"
+    event_id = _INTERNAL_NAME
+
+    def __init__(self, *, adding: bool = False):
+        self._adding = adding
+
+    def locate(self, stream: Stream, target: Target) -> SpliceSite:
+        if target.insert != 0:
+            raise FlpError("effect add is only FL-authored for Master insert 0")
+        events = _events(stream)
+        insert = next(
+            (
+                index
+                for index, (event_id, _head, _end, payload) in enumerate(events)
+                if event_id == EVENT_MIXER_FLAGS and len(payload) == 12
+                and int.from_bytes(payload[:4], "little") == target.insert
+            ),
+            None,
+        )
+        if insert is None:
+            raise FlpError(f"no mixer insert {target.insert}")
+        for index, (event_id, _head, _end, payload) in enumerate(events[insert + 1 :], insert + 1):
+            if event_id == EVENT_MIXER_FLAGS:
+                break
+            if event_id != _SLOT or payload != bytes(2):
+                continue
+            next_event = events[index + 1] if index + 1 < len(events) else None
+            if next_event is not None and next_event[0] == _SLOT:
+                return SpliceSite(next_event[1], next_event[1], None)
+            if next_event is not None and next_event[0] == _INTERNAL_NAME:
+                effect_head = next_event[1]
+                effect_end = _effect_end(events, index + 1)
+                if self._adding:
+                    raise FlpError("mixer insert 0 has no confirmed empty slot 0")
+                return SpliceSite(effect_head, effect_end, bytes(stream[effect_head:effect_end]))
+            break
+        raise FlpError("mixer insert 0 has no confirmed empty slot 0")
+
+    def encode(self, data: Sequence[PluginReference], ppq: int) -> bytes:
+        if len(data) != 1:
+            raise FlpError(f"an effect insertion needs exactly one captured reference, got {len(data)}")
+        (reference,) = data
+        try:
+            decoded = self.decode(reference.chunk, ppq)
+        except (TypeError, AttributeError) as error:
+            raise FlpError("effect reference has no valid captured chunk") from error
+        if len(decoded) != 1 or decoded[0].name != reference.name:
+            raise FlpError(f"captured chunk does not identify {reference.name!r}")
+        # ``patch`` locates once more to verify its saved readback.  Occupancy
+        # is only a pre-insertion requirement for this one-shot format.
+        self._adding = False
+        return reference.chunk
+
+    def frame(self, payload: bytes) -> bytes:
+        """Plugin references are captured event tuples, not synthesized events."""
+        return payload
+
+    def decode(self, blob: bytes, ppq: int) -> list[Effect]:
+        if not blob:
+            return []
+        try:
+            events = _events(Stream(blob))
+            if not events or events[0][0] != _INTERNAL_NAME:
+                raise FlpError("effect tuple does not start with PluginID.InternalName")
+            name = events[0][3].decode("utf-16-le").rstrip("\0")
+            end = _effect_end(events, 0)
+            return [Effect(name, blob[:end])]
+        except UnicodeDecodeError as error:
+            raise FlpError("effect name is not valid UTF-16-LE") from error
+
+    def verify(self, sent: Sequence[Effect], readback: Sequence[Effect]) -> None:
+        verify_identical(sent, readback, "the captured effect reference")
+
+
+def _events(stream: Stream) -> list[tuple[int, int, int, bytes]]:
+    """Fully decoded events with their framing bounds."""
+    events = []
+    head = 0
+    for event_id, offset, size in stream:
+        end = offset + size
+        events.append((event_id, head, end, bytes(stream[offset:end])))
+        head = end
+    return events
+
+
+def _effect_end(events: Sequence[tuple[int, int, int, bytes]], name_index: int) -> int:
+    if name_index + 1 >= len(events) or events[name_index + 1][0] != _WRAPPER:
+        raise FlpError("effect tuple has no plugin wrapper event")
+    state = next(
+        (
+            event
+            for event in events[name_index + 2 :]
+            if event[0] in (_STATE, _INTERNAL_NAME, EVENT_MIXER_FLAGS)
+        ),
+        None,
+    )
+    if state is not None and state[0] == _STATE:
+        return state[2]
+    return events[name_index + 1][2]

flpkit/formats/levels.py

@@ -0,0 +1,97 @@
+"""Channel levels: ONE event (ChannelID.Levels, 219) with a fixed 24-byte
+payload - pan i32 [0:4], volume u32 [4:8], pitch i32 [8:12], filter 12B -
+verified by decoding FL 2026's own stock templates. FL stores fixed-point
+ints; the tool surface is 0..1 volume and -1..1 pan so a model never has to
+know that. A legacy project whose channel has no 219 event is refused
+(FlpError) rather than written with guessed units.
+"""
+
+from __future__ import annotations
+
+import struct
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from flpkit.codec import EVENT_CHANNEL_LEVELS, FlpError, SpliceSite, Stream, Target, verify_identical
+
+LEVEL_MAX = 12800
+PAN_CENTRE = 6400
+VOLUME_DEFAULT = 10000
+
+
+@dataclass(frozen=True)
+class Levels:
+    """One channel's mix state in tool units, plus the opaque 12-byte filter
+    tail carried raw so a rewrite is byte-identical."""
+
+    volume: float  # 0..1
+    pan: float  # -1..1, 0 = centre
+    pitch_semitones: int
+    tail: bytes = bytes(12)
+
+
+class LevelsFormat:
+    name = "levels"
+    event_id = EVENT_CHANNEL_LEVELS
+    frame = None
+
+    def locate(self, stream: Stream, target: Target) -> SpliceSite:
+        """The target channel's Levels event (first 24-byte 219 attributed to
+        it). An unknown channel is IndexError; a channel without one is a
+        legacy-format refusal."""
+        seen: set[int] = set()
+        found = None
+        for channel, event_id, head, off, size in stream.channel_events():
+            if channel is None:
+                continue
+            seen.add(channel)
+            if (
+                event_id == EVENT_CHANNEL_LEVELS and size == 24
+                and channel == target.channel and found is None
+            ):
+                found = (head, off, size)
+        if target.channel not in seen:
+            raise IndexError(f"no channel {target.channel}; project has {len(seen)}")
+        if found is None:
+            raise FlpError(
+                f"channel {target.channel} has no Levels event (id 219); refusing to "
+                "write a legacy-format project with guessed units"
+            )
+        head, off, size = found
+        return SpliceSite(head, off + size, bytes(stream[off : off + size]))
+
+    def encode(self, data: Sequence[Levels], ppq: int) -> bytes:
+        """Exactly one Levels -> the 24-byte payload (tool units re-scaled to
+        FL's fixed-point ints, filter tail verbatim)."""
+        if len(data) != 1:
+            raise FlpError(f"a channel has exactly one Levels, got {len(data)}")
+        (levels,) = data
+        if not 0 <= levels.volume <= 1:
+            raise FlpError(f"volume {levels.volume} out of range (0.0-1.0)")
+        if not -1 <= levels.pan <= 1:
+            raise FlpError(f"pan {levels.pan} out of range (-1.0 to 1.0)")
+        if not -48 <= levels.pitch_semitones <= 48:
+            raise FlpError(f"pitch {levels.pitch_semitones} out of range (-48 to 48)")
+        return (
+            struct.pack(
+                "<iIi",
+                round(PAN_CENTRE + levels.pan * PAN_CENTRE),
+                round(levels.volume * LEVEL_MAX),
+                levels.pitch_semitones,
+            )
+            + levels.tail
+        )
+
+    def decode(self, blob: bytes, ppq: int) -> list[Levels]:
+        pan, volume, pitch = struct.unpack_from("<iIi", blob)
+        return [
+            Levels(
+                volume=volume / LEVEL_MAX,
+                pan=(pan - PAN_CENTRE) / PAN_CENTRE,
+                pitch_semitones=pitch,
+                tail=bytes(blob[12:]),
+            )
+        ]
+
+    def verify(self, sent: Sequence[Levels], readback: Sequence[Levels]) -> None:
+        verify_identical(sent, readback, "the channel's levels")

flpkit/formats/notes.py

@@ -0,0 +1,219 @@
+"""Notes: a pattern's PatternID.Notes blob of 24-byte packed note records.
+
+A pattern's blob holds EVERY channel's notes, so the target scope is one
+channel within one pattern: replacing is scoped to the target channel
+(measured: naive whole-blob replacement of one note on channel 0 wiped 51
+notes on channel 3 of the same pattern).
+"""
+
+from __future__ import annotations
+
+import logging
+import struct
+from collections import Counter
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from flpkit.codec import (
+    EVENT_CHANNEL_NEW,
+    FlpError,
+    SpliceSite,
+    Stream,
+    Target,
+    frame_event,
+    is_channel_scoped,
+    verify_identical,
+)
+
+log = logging.getLogger("flpkit")
+
+EVENT_PATTERN_NEW = 65  # u16 pattern number
+EVENT_PATTERN_NOTES = 224  # varint-length blob of NOTE_STRUCT records
+EVENT_CUR_GROUP_ID = 146  # ProjectID.CurGroupId; the anchor for a new pattern block
+
+# 24-byte packed note record inside a PatternID.Notes blob (matches what FL
+# writes): position u32 (ticks), flags u16, rack_channel u16, length u32
+# (ticks), key u16 (MIDI), group u16, then fine_pitch, u1, release,
+# midi_channel, pan, velocity, mod_x, mod_y - one byte each.
+NOTE_STRUCT = struct.Struct("<IHHIHHBBBBBBBB")
+NOTE_SIZE = 24
+
+# Neutral per-note values FL writes for an ordinary note; wrong defaults show
+# up as notes that play but behave oddly (silent, hard-panned, pitch-shifted).
+FINE_PITCH_CENTER = 120
+RELEASE_DEFAULT = 64
+NOTE_PAN_CENTER = 64
+MOD_DEFAULT = 128
+# Every note FL itself writes carries bit 0x4000. Surveyed across the 132
+# bundled FL 2026 projects that contain notes: 23,526 records with
+# flags=0x4000 and 909 with 0x4008 - and NOT ONE with flags=0. New notes
+# template their flags word from the target file's OWN notes when it has any
+# (detect-don't-assume); this corpus constant is the fallback.
+NOTE_FLAGS_DEFAULT = 0x4000
+
+
+class NoteLike(Protocol):
+    """What a caller-supplied note needs, in tool units: ``key`` is MIDI
+    0-127, ``start``/``length`` are beats, ``velocity``/``pan`` are 0..1
+    (pan 0.5 = centre). Any object with these attributes works."""
+
+    key: int
+    start: float
+    length: float
+    velocity: float
+    pan: float
+
+
+@dataclass(frozen=True)
+class NoteSpec:
+    """A ready-made NoteLike for callers without their own note model."""
+
+    key: int
+    start: float
+    length: float
+    velocity: float = 0.8
+    pan: float = 0.5
+
+
+@dataclass(frozen=True)
+class Note(NoteSpec):
+    """One decoded note record, full-fidelity: the NoteLike tool units plus
+    every raw field the tool surface does not model, so a decoded note
+    re-encodes byte-identically (kept notes survive any rewrite untouched)."""
+
+    channel: int = 0
+    flags: int = NOTE_FLAGS_DEFAULT
+    group: int = 0
+    fine_pitch: int = FINE_PITCH_CENTER
+    u1: int = 0
+    release: int = RELEASE_DEFAULT
+    midi_channel: int = 0
+    mod_x: int = MOD_DEFAULT
+    mod_y: int = MOD_DEFAULT
+    raw_values: bool = field(default=False, repr=False, compare=False)
+
+
+class NotesFormat:
+    name = "notes"
+    event_id = EVENT_PATTERN_NOTES
+    frame = None
+
+    def locate(self, stream: Stream, target: Target) -> SpliceSite:
+        """The target pattern's notes blob (only a 224 event while that
+        pattern is current counts), split into the target channel's records
+        and the rest. One walk also finds where a missing pattern block would
+        splice - after the display-group anchor, where FL itself writes
+        patterns (NOT stream offset 0: ahead of FLVersion, FL refuses the
+        file) - and surveys the file's own note-flags template."""
+        current = 0
+        prev_end = 0
+        pattern_end = existing = anchor_end = channel_section_head = None
+        flags_seen: Counter[int] = Counter()
+        for event_id, off, size in stream:
+            head = prev_end
+            prev_end = off + size
+            if event_id == EVENT_PATTERN_NEW and size == 2:
+                current = int.from_bytes(stream[off : off + size], "little")
+                if current == target.pattern and pattern_end is None:
+                    pattern_end = off + size
+            elif event_id == EVENT_PATTERN_NOTES:
+                if size % NOTE_SIZE == 0:
+                    flags_seen.update(
+                        int.from_bytes(stream[off + at + 4 : off + at + 6], "little")
+                        for at in range(0, size, NOTE_SIZE)
+                    )
+                if current == target.pattern and existing is None:
+                    existing = (head, off, size)
+            elif event_id == EVENT_CUR_GROUP_ID and anchor_end is None:
+                anchor_end = off + size
+            elif (
+                channel_section_head is None
+                and anchor_end is None
+                and (event_id == EVENT_CHANNEL_NEW or is_channel_scoped(event_id))
+            ):
+                channel_section_head = head
+        self._flags = flags_seen.most_common(1)[0][0] if flags_seen else None
+        self._channel = target.channel
+
+        if existing is not None:
+            head, off, size = existing
+            blob = bytes(stream[off : off + size])
+            mine, rest = bytearray(), bytearray()
+            for at in range(0, len(blob) - NOTE_SIZE + 1, NOTE_SIZE):
+                record = blob[at : at + NOTE_SIZE]
+                in_scope = int.from_bytes(record[6:8], "little") == target.channel
+                (mine if in_scope else rest).extend(record)
+            scoped = bytes(mine) if target.channel is not None else None
+            return SpliceSite(head, off + size, blob, scoped=scoped, rest=bytes(rest))
+        if pattern_end is not None:
+            return SpliceSite(pattern_end, pattern_end, None)
+        # No such pattern yet - splice a new pattern block ahead of the event.
+        prelude = frame_event(EVENT_PATTERN_NEW, int(target.pattern or 0).to_bytes(2, "little"))
+        at = anchor_end if anchor_end is not None else channel_section_head
+        at = at if at is not None else len(stream)
+        return SpliceSite(at, at, None, prelude=prelude)
+
+    def encode(self, data: Sequence[NoteLike], ppq: int) -> bytes:
+        """Tool-unit notes -> packed records (ticks; velocity/pan re-scaled).
+        Fields a plain NoteLike does not carry get FL's neutral defaults, the
+        flags word from the file's own template (locate surveyed it; the
+        corpus constant covers a file with no notes yet), and the rack channel
+        from the write target."""
+        flags = getattr(self, "_flags", None)  # locate's survey; None standalone or file had no notes
+        if flags is None:
+            flags = NOTE_FLAGS_DEFAULT
+            log.debug("no existing notes to template flags from; using the corpus default 0x%04x", flags)
+        packed = bytearray()
+        for note in data:
+            if not 0 <= note.key <= 127:
+                raise FlpError(f"note key {note.key} out of range (0-127)")
+            if note.start < 0 or note.length < 0:
+                raise FlpError("note start and length must be non-negative")
+            # Decoded records carry raw values FL may itself place outside the
+            # public tool range. Preserve those opaque facts byte-for-byte.
+            raw_values = getattr(note, "raw_values", False)
+            if not raw_values and (not 0 <= note.velocity <= 1 or not 0 <= note.pan <= 1):
+                raise FlpError("note velocity and pan must be in range 0.0-1.0")
+            packed += NOTE_STRUCT.pack(
+                round(note.start * ppq),
+                getattr(note, "flags", flags),
+                getattr(note, "channel", getattr(self, "_channel", None)) or 0,
+                # Length packs exactly as quantized - NO floor to 1: FL's own
+                # demos carry length-0 records (29 corpus files, e.g. 601 in
+                # 'Astes - Bien Duro'), so kept notes must round-trip raw 0.
+                round(note.length * ppq),
+                note.key,
+                getattr(note, "group", 0),
+                getattr(note, "fine_pitch", FINE_PITCH_CENTER),
+                getattr(note, "u1", 0),
+                getattr(note, "release", RELEASE_DEFAULT),
+                getattr(note, "midi_channel", 0),
+                round(note.pan * 128),
+                round(note.velocity * 127),
+                getattr(note, "mod_x", MOD_DEFAULT),
+                getattr(note, "mod_y", MOD_DEFAULT),
+            )
+        return bytes(packed)
+
+    def decode(self, blob: bytes, ppq: int) -> list[Note]:
+        """Unpack records to full-fidelity notes in beats/0..1 tool units
+        (exact: every field re-encodes to the same bytes). Raises FlpError on
+        a truncated blob."""
+        if len(blob) % NOTE_SIZE:
+            raise FlpError(f"notes blob of {len(blob)} bytes is not a multiple of {NOTE_SIZE}")
+        return [
+            Note(
+                key=key, start=position / ppq, length=length / ppq,
+                velocity=velocity / 127, pan=pan / 128,
+                channel=channel, flags=flags, group=group, fine_pitch=fine_pitch,
+                u1=u1, release=release, midi_channel=midi_channel, mod_x=mod_x, mod_y=mod_y, raw_values=True,
+            )
+            for (
+                position, flags, channel, length, key, group,
+                fine_pitch, u1, release, midi_channel, pan, velocity, mod_x, mod_y,
+            ) in NOTE_STRUCT.iter_unpack(blob)
+        ]
+
+    def verify(self, sent: Sequence[Note], readback: Sequence[Note]) -> None:
+        verify_identical(sent, readback, "the pattern's notes")

flpkit/formats/playlist.py

@@ -0,0 +1,173 @@
+"""Playlist: an arrangement's PlaylistID.Items blob of fixed-stride records.
+
+The 16-byte record head is constant across eras (see detect.py, which infers
+the era's record size from the pattern_base==20480 signature); the rest of a
+record is era-opaque, so every record is built from a byte TEMPLATE - the
+first existing record in the target blob - and a playlist with no existing
+record has no honest template (FlpError, never invented tail bytes).
+"""
+
+from __future__ import annotations
+
+import struct
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+from flpkit.codec import FlpError, SpliceSite, Stream, Target, verify_identical
+from flpkit.detect import PATTERN_INDEX_BASE, PLAYLIST_TRACK_SPACE, playlist_stride
+
+EVENT_ARRANGEMENT_NEW = 99  # u16 arrangement index; starts an arrangement block
+EVENT_PLAYLIST = 233  # blob of playlist-item records
+RECORD_HEAD = struct.Struct("<IHHIHH")  # position, pattern_base, item_index, length, track_rvidx, group
+
+# Bytes 24-31 are the clip's cut window in TICKS (u32 start, u32 end) - NOT
+# the f32 offsets pyflp documents. Proven live: FL 2026 derives the visible
+# clip length from this window (a zeroed window collapsed the clip to length 1
+# and FL rewrote the head length field to match on its next save). An uncut
+# clip spans 0..length. EXISTING records' windows are era-opaque bytes and
+# are never touched or interpreted - legacy eras stamp f32 shapes there
+# (corpus: FL-bundled demo/legacy projects), and the e2e matrix proved live
+# that FL 2026 accepts our modern window on NEW records beside them.
+_WINDOW_AT = 24
+
+
+class ClipLike(Protocol):
+    """What a caller-supplied clip needs, in tool units: a pattern number
+    placed on a 1-based playlist track, ``start``/``length`` in beats."""
+
+    pattern: int
+    track: int
+    start: float
+    length: float
+
+
+@dataclass(frozen=True)
+class ClipSpec:
+    """A ready-made ClipLike for callers without their own clip model."""
+
+    pattern: int
+    track: int
+    start: float
+    length: float
+
+
+@dataclass(frozen=True)
+class Clip:
+    """One decoded record: the head in tool units plus the era-opaque tail
+    (record bytes 16..stride, cut window included) carried raw, so a decoded
+    clip re-encodes byte-identically."""
+
+    track: int
+    start: float  # beats
+    length: float  # beats
+    pattern: int | None = None  # set for pattern clips
+    channel: int | None = None  # set for audio/automation channel clips
+    group: int = 0
+    tail: bytes = b""
+
+
+class PlaylistFormat:
+    name = "playlist"
+    event_id = EVENT_PLAYLIST
+    frame = None
+
+    def locate(self, stream: Stream, target: Target) -> SpliceSite:
+        """The target arrangement's playlist event (arrangement events switch
+        the current index; 0 before any). Captures the write template - the
+        first existing record; its window bytes are overwritten per new
+        clip, everything else is carried verbatim."""
+        arrangement = target.arrangement or 0
+        current = 0
+        prev_end = 0
+        existing = None
+        for event_id, off, size in stream:
+            head = prev_end
+            prev_end = off + size
+            if event_id == EVENT_ARRANGEMENT_NEW and size == 2:
+                current = int.from_bytes(stream[off : off + size], "little")
+            elif event_id == EVENT_PLAYLIST and current == arrangement and existing is None:
+                existing = (head, off, size)
+
+        self._template: bytes | None = None
+        self._refusal = (
+            f"arrangement {arrangement} has no playlist event; a write needs "
+            "one existing clip as a byte template"
+        )
+        if existing is None:
+            return SpliceSite(len(stream), len(stream), None)
+        head, off, size = existing
+        blob = bytes(stream[off : off + size])
+        stride = playlist_stride(blob)
+        if stride is None or not blob:
+            self._refusal = (
+                f"arrangement {arrangement}: playlist blob of {len(blob)} bytes "
+                "fits no known record size; no honest template"
+            )
+            return SpliceSite(head, off + size, blob)
+        self._template = blob[:stride]
+        self._refusal = None
+        return SpliceSite(head, off + size, blob)
+
+    def encode(self, data: Sequence[ClipLike], ppq: int) -> bytes:
+        """Tool-unit clips -> position-sorted records (all 54 corpus
+        arrangements are stored that way). New records inherit the template's
+        era tail with the uncut window packed in; decoded clips carry their
+        own tail verbatim."""
+        refusal = getattr(self, "_refusal", None)  # set by locate on the write path
+        if refusal:
+            raise FlpError(refusal)
+        records = []
+        for clip in data:
+            if not 1 <= clip.track <= PLAYLIST_TRACK_SPACE:
+                raise ValueError(f"track {clip.track} outside 1..{PLAYLIST_TRACK_SPACE}")
+            # Exactly as quantized, no floor - decoded records must round-trip
+            # their raw length byte-identically (same rule as notes).
+            length = round(clip.length * ppq)
+            tail = getattr(clip, "tail", b"")
+            if not tail:
+                template = getattr(self, "_template", None)
+                if template is None:
+                    raise FlpError("a new clip needs the located byte template; write through codec.patch")
+                tail = bytearray(template[RECORD_HEAD.size :])
+                struct.pack_into("<II", tail, _WINDOW_AT - RECORD_HEAD.size, 0, length)
+            pattern = getattr(clip, "pattern", None)
+            item_index = PATTERN_INDEX_BASE + pattern if pattern is not None else clip.channel
+            records.append(
+                RECORD_HEAD.pack(
+                    round(clip.start * ppq), PATTERN_INDEX_BASE, item_index, length,
+                    PLAYLIST_TRACK_SPACE - clip.track, getattr(clip, "group", 0),
+                )
+                + bytes(tail)
+            )
+        records.sort(key=lambda r: struct.unpack_from("<I", r)[0])
+        return b"".join(records)
+
+    def decode(self, blob: bytes, ppq: int) -> list[Clip]:
+        """Records -> tool-unit clips at the detected stride. Raises FlpError
+        when no stride fits (a new FL era) - the project reader surfaces that
+        as a per-event warning, never a crash."""
+        if not blob:
+            return []
+        stride = playlist_stride(blob)
+        if stride is None:
+            raise FlpError(f"playlist blob of {len(blob)} bytes fits no record size (new era?)")
+        clips = []
+        for at in range(0, len(blob), stride):
+            position, _base, item_index, length, track_rvidx, group = RECORD_HEAD.unpack_from(blob, at)
+            is_pattern = item_index >= PATTERN_INDEX_BASE
+            clips.append(
+                Clip(
+                    track=PLAYLIST_TRACK_SPACE - track_rvidx,
+                    start=position / ppq,
+                    length=length / ppq,
+                    pattern=item_index - PATTERN_INDEX_BASE if is_pattern else None,
+                    channel=None if is_pattern else item_index,
+                    group=group,
+                    tail=blob[at + RECORD_HEAD.size : at + stride],
+                )
+            )
+        return clips
+
+    def verify(self, sent: Sequence[Clip], readback: Sequence[Clip]) -> None:
+        verify_identical(sent, readback, "the arrangement's playlist")