flpkit 0.8.1__py3-none-any.whl

flpkit/codec.py

@@ -0,0 +1,317 @@
+"""The ONE read+write engine over the FLP event stream.
+
+A .flp element type (notes, playlist, automation, levels, tempo, effects) implements
+the ``Format`` protocol; :func:`read` and :func:`patch` are the only paths
+that touch the file. All the messy splice and chunk-length math lives here,
+once. Writes are raw byte surgery - patch exactly the bytes that express the
+change, never reserialize the whole file (FL rejects whole-file
+reserialization by third-party writers; verified live 2026-08-27) - and every
+write verifies itself by re-reading the saved file.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Literal, Protocol
+
+from .detect import resolve_size_overrides
+
+Mode = Literal["merge", "replace"]
+
+
+class FlpError(ValueError):
+    """Malformed .flp input or a write whose readback did not match."""
+
+
+# -- stream structure facts (verified live; see the parent project's e2e suite)
+EVENT_CHANNEL_NEW = 64  # u16 channel IID; starts that channel's event block
+EVENT_MIXER_FLAGS = 236  # InsertID.Flags; first one means the mixer section began
+EVENT_CHANNEL_TYPE = 21  # 1 byte; 5 marks an automation channel
+EVENT_CHANNEL_LEVELS = 219  # 24B: pan i32, volume u32, pitch i32, filter 12B
+EVENT_CHANNEL_AUTOMATION = 234  # the channel's automation points blob
+EVENT_NAME_LEGACY = 192  # ChannelID._Name
+EVENT_NAME_INTERNAL = 201  # PluginID.InternalName (e.g. the generator name)
+EVENT_NAME_USER = 203  # PluginID.Name (the user-visible rename)
+EVENT_VOL_WORD = 72  # legacy per-channel volume (pre-Levels files)
+EVENT_PAN_WORD = 73  # legacy per-channel pan
+EVENT_VOL_BYTE = 2  # older still
+EVENT_PAN_BYTE = 3
+
+# Events that belong to the currently open rack channel.
+CHANNEL_SCOPED = frozenset((
+    EVENT_CHANNEL_TYPE, EVENT_CHANNEL_LEVELS, EVENT_CHANNEL_AUTOMATION,
+    EVENT_NAME_LEGACY, EVENT_NAME_INTERNAL, EVENT_NAME_USER,
+    EVENT_VOL_WORD, EVENT_PAN_WORD, EVENT_VOL_BYTE, EVENT_PAN_BYTE,
+))
+
+
+def is_channel_scoped(event_id: int) -> bool:
+    return event_id in CHANNEL_SCOPED
+
+
+@dataclass(frozen=True)
+class Target:
+    """Which element instance a Format addresses; unused fields stay None."""
+
+    pattern: int | None = None
+    channel: int | None = None
+    arrangement: int | None = None
+    insert: int | None = None
+
+
+@dataclass(frozen=True)
+class SpliceSite:
+    """Everything one locating walk found about WHERE an element lives.
+
+    ``scoped``/``rest`` split the payload by the target: :func:`read` decodes
+    ``scoped``; a replace write keeps ``rest`` and drops ``scoped`` (a merge
+    keeps everything). Formats whose whole payload IS the target scope leave
+    them at their defaults.
+    """
+
+    head: int  # stream offset where the element's event begins (or will)
+    end: int  # just past the existing event; == head when the element is absent
+    payload: bytes | None  # the existing element's payload; None = no event yet
+    scoped: bytes | None = None  # target-scoped subset of payload; None = all of it
+    rest: bytes = b""  # payload outside the scope, in file order
+    prelude: bytes = b""  # event bytes spliced ahead when creating the element
+
+
+class Format(Protocol):
+    """The contract a .flp element type implements. Reading an implementation
+    tells you how that element is found, packed, unpacked, and checked -
+    nothing hidden in the engine. An instance is call-scoped: ``locate`` runs
+    first and may capture in-file templates (a flags word, a record template,
+    a header/trailer) that ``encode`` then carries (detect-don't-assume)."""
+
+    name: str  # "notes", "playlist", "automation", "levels", "tempo", "effects"
+    event_id: int  # the FLP event that carries it
+    frame: Callable[[bytes], bytes] | None  # custom event framing, if needed
+
+    def locate(self, stream: Stream, target: Target) -> SpliceSite:
+        """WHERE this element lives (e.g. notes: the pattern's blob)."""
+        ...
+
+    def encode(self, data: Sequence[Any], ppq: int) -> bytes:
+        """Tool units -> the element's file bytes (validating the input)."""
+        ...
+
+    def decode(self, blob: bytes, ppq: int) -> list[Any]:
+        """File bytes -> tool units; byte-faithful (encode of the result
+        reproduces ``blob`` exactly), so kept items survive any rewrite."""
+        ...
+
+    def verify(self, sent: Sequence[Any], readback: Sequence[Any]) -> None:
+        """Raise FlpError unless the saved file decodes to exactly ``sent``."""
+        ...
+
+def read(
+    path: Path,
+    fmt: Format,
+    target: Target,
+    *,
+    event_size_overrides: Mapping[int, int] | None = None,
+) -> list[Any]:
+    """locate -> decode. The only element read path."""
+    _header, ppq, stream = _open(path.read_bytes(), event_size_overrides)
+    site = fmt.locate(stream, target)
+    return fmt.decode(_scope(site), ppq)
+
+
+def patch(
+    path: Path,
+    fmt: Format,
+    target: Target,
+    data: Sequence[Any],
+    mode: Mode,
+    *,
+    event_size_overrides: Mapping[int, int] | None = None,
+) -> list[Any]:
+    """locate -> encode -> splice + fix chunk lengths -> re-read -> fmt.verify.
+
+    The only write path. The new payload is ``encode`` over the kept items
+    (all of them on merge, only the out-of-scope ``rest`` on replace) plus
+    ``data``; the readback IS the contract - the saved file must decode to
+    exactly what was spliced, or FlpError. Returns the target-scoped readback.
+    """
+    if mode not in ("merge", "replace"):
+        raise FlpError(f"unsupported patch mode {mode!r}; expected 'merge' or 'replace'")
+
+    raw = bytearray(path.read_bytes())
+    header, ppq, stream = _open(bytes(raw), event_size_overrides)
+    base = 8 + len(header) + 8  # the FLdt payload's file offset
+
+    site = fmt.locate(stream, target)
+    kept_blob = site.payload if mode == "merge" else site.rest
+    kept = fmt.decode(kept_blob, ppq) if kept_blob else []
+    payload = fmt.encode([*kept, *data], ppq)
+
+    frame = fmt.frame
+    event = site.prelude + (frame(payload) if frame is not None else frame_event(fmt.event_id, payload))
+    raw[base + site.head : base + site.end] = event
+    _bump_fldt_length(raw, len(event) - (site.end - site.head))
+    path.write_bytes(bytes(raw))
+
+    _, _, saved_stream = _open(path.read_bytes(), event_size_overrides)
+    saved = fmt.locate(saved_stream, target)
+    fmt.verify(fmt.decode(payload, ppq), fmt.decode(saved.payload or b"", ppq))
+    return fmt.decode(_scope(saved), ppq)
+
+
+def verify_identical(sent: Sequence[Any], readback: Sequence[Any], context: str) -> None:
+    """The one readback contract: the saved element decodes to exactly what
+    was sent - same items, same order. Raises FlpError naming the first drift."""
+    if list(readback) == list(sent):
+        return
+    drift = next(
+        (f"item {i}: sent {s!r}, read back {r!r}" for i, (s, r) in enumerate(zip(sent, readback)) if s != r),
+        f"sent {len(sent)} items, read back {len(readback)}",
+    )
+    raise FlpError(f"readback of {context} does not match the write: {drift}")
+
+
+def _scope(site: SpliceSite) -> bytes:
+    return site.scoped if site.scoped is not None else (site.payload or b"")
+
+
+def _open(data: bytes, overrides: Mapping[int, int] | None) -> tuple[bytes, int, Stream]:
+    header, raw = chunks(data)
+    return header, int.from_bytes(header[4:6], "little"), Stream(raw, overrides)
+
+
+# -- the wire format ----------------------------------------------------------
+
+
+def chunks(data: bytes) -> tuple[bytes, memoryview]:
+    """Split FLhd header / FLdt event stream; raises FlpError on a non-FLP file.
+
+    Layout: b"FLhd" + u32 len(6) + (u16 format, u16 nChannels, u16 ppq),
+    then b"FLdt" + u32 len + the event stream.
+    """
+    if data[:4] != b"FLhd":
+        raise FlpError("not an FLP file: no FLhd magic at offset 0")
+    if len(data) < 8:
+        raise FlpError(f"truncated FLhd chunk: file is only {len(data)} bytes")
+    hd_len = int.from_bytes(data[4:8], "little")
+    if hd_len < 6 or 8 + hd_len > len(data):
+        raise FlpError(f"bad FLhd length {hd_len} at offset 4")
+    header = data[8 : 8 + hd_len]
+    # pyflp's FileFormat set: None_/Project/Score/Automation/ChannelState/
+    # PluginState/GeneratorState/FXState/InsertState/Patcher.
+    file_format = int.from_bytes(header[0:2], "little", signed=True)
+    if file_format not in (-1, 0, 0x10, 24, 0x20, 0x30, 0x31, 0x32, 0x40, 0x50):
+        raise FlpError(f"unknown FLP format {file_format} at offset 8")
+    dt_off = 8 + hd_len
+    if data[dt_off : dt_off + 4] != b"FLdt":
+        raise FlpError(f"no FLdt magic at offset {dt_off}")
+    if dt_off + 8 > len(data):
+        raise FlpError(f"truncated FLdt chunk header at offset {dt_off}")
+    dt_len = int.from_bytes(data[dt_off + 4 : dt_off + 8], "little")
+    start = dt_off + 8
+    if start + dt_len > len(data):
+        raise FlpError(
+            f"FLdt length {dt_len} at offset {dt_off + 4} overruns the file ({len(data)} bytes)"
+        )
+    return header, memoryview(data)[start : start + dt_len]
+
+
+class Stream:
+    """The FLdt event stream: slices like a memoryview, iterates as events.
+
+    Event encoding: id < 64 -> 1 data byte, 64-127 -> 2, 128-191 -> 4,
+    192+ -> varint length + payload, except the measured size-override table
+    (resolved by detect.py; a capability profile's detected table wins over
+    the built-in fallback). Iteration yields (event_id, payload_offset,
+    payload_size), offsets relative to the stream; raises FlpError on
+    truncation.
+    """
+
+    def __init__(self, raw: memoryview | bytes, size_overrides: Mapping[int, int] | None = None):
+        self.raw = raw if isinstance(raw, memoryview) else memoryview(raw)
+        self.size_overrides = resolve_size_overrides(size_overrides)
+
+    def __getitem__(self, key):
+        return self.raw[key]
+
+    def __len__(self) -> int:
+        return len(self.raw)
+
+    def __iter__(self) -> Iterator[tuple[int, int, int]]:
+        stream, overrides, end = self.raw, self.size_overrides, len(self.raw)
+        pos = 0
+        while pos < end:
+            head = pos
+            event_id = stream[pos]
+            pos += 1
+            if event_id in overrides:
+                size = overrides[event_id]
+            elif event_id < 192:
+                size = 1 if event_id < 64 else 2 if event_id < 128 else 4
+            else:
+                size = 0
+                shift = 0
+                while True:
+                    if pos >= end:
+                        raise FlpError(f"truncated varint for event {event_id} at stream offset {head}")
+                    byte = stream[pos]
+                    pos += 1
+                    size |= (byte & 0x7F) << shift
+                    shift += 7
+                    if not byte & 0x80:
+                        break
+            if pos + size > end:
+                raise FlpError(
+                    f"event {event_id} payload of {size} bytes at stream offset {head} "
+                    f"overruns the stream ({end} bytes)"
+                )
+            yield event_id, pos, size
+            pos += size
+
+    def channel_events(self) -> Iterator[tuple[int | None, int, int, int, int]]:
+        """Iterate events with rack-channel attribution: yields (channel,
+        event_id, head, off, size), ``channel`` None outside the channel
+        section. The rule (corpus-verified on all 164 bundled projects):
+        CHANNEL 0 IS IMPLICIT - a channel-scoped event with no channel open
+        yet opens channel 0 (stock 'Basic with limiter' does this; found
+        live); New(64)=N opens/switches to channel N; the first mixer event
+        ends attribution (slot plugin names are not channel names)."""
+        current: int | None = None
+        mixer_seen = False
+        prev_end = 0
+        for event_id, off, size in self:
+            head = prev_end
+            prev_end = off + size
+            channel: int | None = None
+            if event_id == EVENT_CHANNEL_NEW and size == 2 and not mixer_seen:
+                current = channel = int.from_bytes(self.raw[off : off + size], "little")
+            elif event_id == EVENT_MIXER_FLAGS:
+                mixer_seen = True
+                current = None
+            elif is_channel_scoped(event_id) and not mixer_seen:
+                current = current if current is not None else 0
+                channel = current
+            yield channel, event_id, head, off, size
+
+
+def frame_event(event_id: int, payload: bytes) -> bytes:
+    """Frame one event: fixed-size payload below id 192, else a varint length
+    (7 bits per byte, high bit = continue) then the payload."""
+    if event_id < 192:
+        return bytes([event_id]) + payload
+    length = bytearray()
+    n = len(payload)
+    while True:
+        length.append((n & 0x7F) | (0x80 if n > 0x7F else 0))
+        n >>= 7
+        if not n:
+            break
+    return bytes([event_id]) + bytes(length) + payload
+
+
+def _bump_fldt_length(data: bytearray, delta: int) -> None:
+    hd_len = int.from_bytes(data[4:8], "little")
+    dt_len_off = 8 + hd_len + 4
+    old_len = int.from_bytes(data[dt_len_off : dt_len_off + 4], "little")
+    data[dt_len_off : dt_len_off + 4] = (old_len + delta).to_bytes(4, "little")

flpkit/data/plugins/fruity-parametric-eq-2.json

@@ -0,0 +1,8 @@
+{
+  "name": "Fruity Parametric EQ 2",
+  "fl_build": "26.1.5.5384",
+  "kind": "mixer-effect",
+  "captured_on": "2026-09-01",
+  "sha256": "cb3358762c19cab2b91977938f62e100db1ee4a0fa4d4e228d6c79cdf1685cd5",
+  "chunk_hex": "c92e460072007500690074007900200050006100720061006d0065007400720069006300200045005100200032000000d434000000000100000002000000000000004001000000000000000000000000000000000000540000007e000000bc0200005e010000cb2e460072007500690074007900200050006100720061006d00650074007200690063002000450051002000320000009b0000000080485156002900d5e2020800000000000000000000000000000000000000000000000000000000000000ab2a00001c4700008e63000000800000729c0000e4b8000055d50000bc9c00004463000044630000446300004463000044630000bc9c000005000000060000000600000006000000060000000600000007000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000ab2a00001c4700008e63000000800000729c0000e4b8000055d50000bc9c00004463000044630000446300004463000044630000bc9c000005000000060000000600000006000000060000000600000007000000000000000000000000000000000000000000000000000000000000000000000003000000000000000102000000010000000200000000000000407f0000000100000000000000030000000100000002000000020000000200000000000000"
+}

flpkit/data/plugins/index.json

@@ -0,0 +1,3 @@
+{
+  "Fruity Parametric EQ 2": "fruity-parametric-eq-2.json"
+}

flpkit/detect.py

@@ -0,0 +1,83 @@
+"""Signature detection: the ONLY place flpkit infers a size or a stride.
+
+FL grows record layouts era by era without version-tagging them, so every
+era-variable size here is DETECTED from an in-data signature, with a
+hardcoded FL-2026-measured table as the warned fallback (detect-don't-assume).
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import struct
+from collections.abc import Mapping
+
+log = logging.getLogger("flpkit")
+
+# Events whose size breaks the classic range rule. 172 is a ONE-byte event:
+# verified by full-stream consistency on 16 FL-2026-authored files (every one
+# consumes exactly, with ChannelID.New counts matching the FLhd header) and on
+# the two shipped templates that contain it - under the classic 4-byte read,
+# "Basic with limiter" loses a channel AND its tempo event to the desync.
+# pyflp shares the 4-byte bug (it cannot parse fresh FL 2026 saves at all),
+# so this table is where flpkit deliberately diverges from the oracle.
+# It is the FALLBACK: every public function takes ``event_size_overrides`` so
+# a capability profile's offline-detected table wins over this hardcoded one;
+# falling back here is logged once per process.
+EVENT_SIZE_OVERRIDES_FALLBACK: Mapping[int, int] = {172: 1}
+
+
+@functools.cache
+def _log_size_override_fallback() -> None:
+    log.info(
+        "no event_size_overrides provided; falling back to the built-in "
+        "FL-2026-measured table %r (a capability profile can supply the "
+        "detected table for other FL versions)",
+        EVENT_SIZE_OVERRIDES_FALLBACK,
+    )
+
+
+def resolve_size_overrides(overrides: Mapping[int, int] | None) -> Mapping[int, int]:
+    if overrides is not None:
+        return overrides
+    _log_size_override_fallback()
+    return EVENT_SIZE_OVERRIDES_FALLBACK
+
+
+# Playlist item records: the 16-byte decoded head is constant across eras -
+# position u32, pattern_base u16 (ALWAYS 20480 - the per-record signature),
+# item_index u16 (pattern iid+20480, else channel iid), length u32,
+# track_rvidx u16 (reversed: track 1 = 499 in the 500-track space), group u16.
+# The RECORD SIZE grows era by era: 32 (classic), 60 (FL 21), 80 (observed in
+# 17 of FL's bundled demos), 88 (FL 2026, decoded exactly against a project
+# whose playlist visibly held 4 clips). Rather than hardcode that list, the
+# stride is DETECTED: the smallest 4-byte-aligned size >= 32 that divides the
+# blob and puts pattern_base == 20480 (and a sane track) at EVERY record head.
+# All 49 corpus files with playlists resolve unambiguously under this rule.
+PLAYLIST_STRIDE_MIN = 32
+PLAYLIST_STRIDE_MAX = 256
+PLAYLIST_TRACK_SPACE = 500  # track number = PLAYLIST_TRACK_SPACE - track_rvidx
+PATTERN_INDEX_BASE = 20480  # item_index >= this means a pattern clip
+
+
+def _stride_fits(blob: bytes, stride: int) -> bool:
+    """True when every stride-aligned record head carries the pattern_base
+    signature (20480) and a track index inside the 500-track space."""
+    for at in range(0, len(blob), stride):
+        (base,) = struct.unpack_from("<H", blob, at + 4)
+        (rvidx,) = struct.unpack_from("<H", blob, at + 12)
+        if base != PATTERN_INDEX_BASE or not 0 <= PLAYLIST_TRACK_SPACE - rvidx <= PLAYLIST_TRACK_SPACE:
+            return False
+    return True
+
+
+def playlist_stride(blob: bytes) -> int | None:
+    """The detected record size of a playlist blob, None when nothing fits."""
+    return next(
+        (
+            s
+            for s in range(PLAYLIST_STRIDE_MIN, PLAYLIST_STRIDE_MAX + 1, 4)
+            if len(blob) % s == 0 and _stride_fits(blob, s)
+        ),
+        None,
+    )

flpkit/formats/__init__.py

@@ -0,0 +1,17 @@
+"""DATA-like Format implementations: each module states ONE .flp element -
+how it is found (locate), packed (encode), unpacked (decode), and checked
+(verify). Reading one module IS that feature; the engine is codec.py."""
+
+from .automation import AutomationFormat
+from .effects import EffectFormat
+from .levels import LevelsFormat
+from .notes import NotesFormat
+from .playlist import PlaylistFormat
+from .tempo import TempoFormat
+
+# Every Format this library ships, for generic iteration (e.g. round-trip
+# suites). Classes, not instances: a Format instance is call-scoped (its
+# locate captures in-file templates), so construct one per use.
+ALL = (NotesFormat, PlaylistFormat, AutomationFormat, LevelsFormat, TempoFormat, EffectFormat)
+
+__all__ = ["ALL", "AutomationFormat", "EffectFormat", "LevelsFormat", "NotesFormat", "PlaylistFormat", "TempoFormat"]

flpkit/formats/automation.py

@@ -0,0 +1,189 @@
+"""Automation: a type-5 channel's points blob (event 234).
+
+Blob layout (pyflp-verified field map, corpus-verified sizes): 17B header,
+point count u32 at 17, then 24B points - x_delta f64 (BEATS from the previous
+point; corpus positions land on clean beat fractions), value f64 (0..1),
+tension f32, 4B tension-linked tail. After the points FL writes a trailer
+(112 bytes in 1098 of 1100 corpus blobs, 136 in 2). Writes are correct by
+construction, not by decoding: the header and the era trailer are carried
+verbatim from the channel's own blob, only the count and the point records
+between them are rebuilt. A channel that is not kind 5 or has no blob is an
+error, not an invitation to fabricate: creating a NEW clip needs live
+minimal-pair evidence this writer deliberately does not guess at.
+"""
+
+from __future__ import annotations
+
+import logging
+import struct
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+from flpkit.codec import (
+    EVENT_CHANNEL_AUTOMATION,
+    EVENT_CHANNEL_TYPE,
+    FlpError,
+    SpliceSite,
+    Stream,
+    Target,
+    verify_identical,
+)
+
+log = logging.getLogger("flpkit")
+
+CHANNEL_TYPE_AUTOMATION = 5  # corpus: all 1100 automation blobs sit in type-5 channels
+_COUNT_AT = 17
+_POINTS_AT = 21
+_POINT_SIZE = 24
+_TAIL_AT = 20  # tail offset inside one 24-byte point record
+# The tail FL writes on a plain point (corpus: 1,093 of 9,676 points carry
+# exactly this, typically a clip's first point; the rest vary per point, which
+# is why decoded points carry their own tail bytes for byte-faithful rewrites).
+AUTOMATION_TAIL_DEFAULT = bytes(4)
+# FL itself stores values a hair outside 0..1 (corpus max 1.0000403), so input
+# validation allows the same slack rather than refusing FL's own data.
+_VALUE_SLACK = 0.001
+
+
+class AutomationPointLike(Protocol):
+    """What a caller-supplied point needs: ``position`` is beats from clip
+    start (absolute; the writer converts back to FL's stored x-deltas),
+    ``value`` is normalized 0..1, ``tension`` -1..1. A point may also carry a
+    4-byte ``tail`` attribute (FL's opaque per-point tail); points without one
+    get the plain-point default."""
+
+    position: float
+    value: float
+    tension: float
+
+
+@dataclass(frozen=True)
+class AutomationPointSpec:
+    """A ready-made AutomationPointLike for callers without their own model."""
+
+    position: float
+    value: float
+    tension: float = 0.0
+
+
+@dataclass(frozen=True)
+class FlpAutomationPoint:
+    """One decoded point, relative to the clip start. ``tail`` is FL's opaque
+    4-byte per-point tail, carried raw so a decoded clip rewrites
+    readback-identically; byte-identically for FL-authored blobs
+    (corpus-tested)."""
+
+    position: float  # beats from clip start
+    value: float  # normalized 0..1
+    tension: float
+    tail: bytes = AUTOMATION_TAIL_DEFAULT
+
+
+class AutomationFormat:
+    name = "automation"
+    event_id = EVENT_CHANNEL_AUTOMATION
+    frame = None
+
+    def locate(self, stream: Stream, target: Target) -> SpliceSite:
+        """The target channel's automation blob, refusing dishonest ground:
+        an unknown channel (IndexError), a non-type-5 channel, a channel with
+        no blob, or a blob whose count overruns it. Captures the header and
+        the era trailer for encode to carry verbatim."""
+        seen: set[int] = set()
+        kind = None
+        found = None
+        for channel, event_id, head, off, size in stream.channel_events():
+            if channel is None:
+                continue
+            seen.add(channel)
+            if channel != target.channel:
+                continue
+            if event_id == EVENT_CHANNEL_TYPE and size == 1:
+                kind = stream[off]
+            elif event_id == EVENT_CHANNEL_AUTOMATION 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 kind != CHANNEL_TYPE_AUTOMATION:
+            raise FlpError(
+                f"channel {target.channel} is kind {kind}, not an automation channel "
+                f"(kind {CHANNEL_TYPE_AUTOMATION}); refusing to write points into it"
+            )
+        if found is None:
+            raise FlpError(
+                f"channel {target.channel} has no automation blob (event "
+                f"{EVENT_CHANNEL_AUTOMATION}); only existing clips are patched - "
+                "creating one needs undecoded header/trailer/link bytes"
+            )
+        head, off, size = found
+        blob = bytes(stream[off : off + size])
+        if len(blob) < _POINTS_AT:
+            raise FlpError(
+                f"channel {target.channel} automation blob of {len(blob)} bytes is "
+                "truncated; no honest header to carry"
+            )
+        (count,) = struct.unpack_from("<I", blob, _COUNT_AT)
+        points_end = _POINTS_AT + count * _POINT_SIZE
+        if points_end > len(blob):
+            raise FlpError(
+                f"channel {target.channel} automation blob claims {count} points but "
+                f"holds {len(blob)} bytes; refusing to guess where the trailer starts"
+            )
+        self._header = blob[:_COUNT_AT]
+        self._trailer = blob[points_end:]
+        return SpliceSite(head, off + size, blob)
+
+    def encode(self, data: Sequence[AutomationPointLike], ppq: int) -> bytes:
+        """Points -> header (verbatim) + count + 24B records + trailer
+        (verbatim). Points are sorted by position first; FL stores forward
+        x-deltas (zero deltas, i.e. vertical steps, are fine)."""
+        ordered = sorted(data, key=lambda p: p.position)
+        for p in ordered:
+            if not -_VALUE_SLACK <= p.value <= 1 + _VALUE_SLACK:
+                raise ValueError(f"point value {p.value} out of range (normalized 0..1)")
+            if not -1.0 <= p.tension <= 1.0:
+                raise ValueError(f"point tension {p.tension} out of range (-1..1)")
+            tail = getattr(p, "tail", None)
+            if tail is not None and len(tail) != 4:
+                raise ValueError(f"point tail must be 4 bytes, got {len(tail)}")
+        if ordered and ordered[0].position < 0:
+            raise ValueError(f"point position {ordered[0].position} is negative")
+        body = bytearray(self._header)
+        body += struct.pack("<I", len(ordered))
+        prev = 0.0
+        for p in ordered:
+            tail = getattr(p, "tail", None)
+            body += struct.pack("<ddf", p.position - prev, p.value, p.tension)
+            body += bytes(tail) if tail is not None else AUTOMATION_TAIL_DEFAULT
+            prev = p.position
+        return bytes(body) + self._trailer
+
+    def decode(self, blob: bytes, ppq: int) -> list[FlpAutomationPoint]:
+        """Points with cumulative-sum x_delta -> absolute positions. A
+        malformed blob decodes to no points, with a warning - the project
+        reader's never-crash contract (the write path refuses these in
+        locate, before any byte moves)."""
+        if len(blob) < _POINTS_AT:
+            log.warning("automation blob of %d bytes is truncated", len(blob))
+            return []
+        (count,) = struct.unpack_from("<I", blob, _COUNT_AT)
+        if _POINTS_AT + count * _POINT_SIZE > len(blob):
+            log.warning("automation blob claims %d points but holds %d bytes", count, len(blob))
+            return []
+        points = []
+        position = 0.0
+        for i in range(count):
+            at = _POINTS_AT + i * _POINT_SIZE
+            delta, value, tension = struct.unpack_from("<ddf", blob, at)
+            position += delta
+            points.append(
+                FlpAutomationPoint(
+                    position=position, value=value, tension=tension,
+                    tail=bytes(blob[at + _TAIL_AT : at + _POINT_SIZE]),
+                )
+            )
+        return points
+
+    def verify(self, sent: Sequence[FlpAutomationPoint], readback: Sequence[FlpAutomationPoint]) -> None:
+        verify_identical(sent, readback, "the channel's automation points")