switchnote/FORMAT.md

# Switchnote `.sppm` format

`.sppm` is Switchnote Studio's own offline animation format. It is not a Nintendo `.ppm`
file. All integers are unsigned little-endian unless stated otherwise. Readers
must check every length before allocating or advancing. `include/sppm.hpp` and
`source/sppm.cpp` are the reference implementation.

The Fakenote Studio repository supplies 1280×720 UI mockups and 640×360 sample
artwork, with editor buttons for layers A through D. It does **not** specify a
binary format or an exact ink palette. The payload uses a 640×360
canvas, four indexed layers, and 256 editable RGBA palette entries. Entry 0 is
transparent. The four layers composite D, C, B, A from back to front; pattern
brushes write ordinary palette indices in their chosen pattern.

## Header

| Offset | Size | Value |
| ---: | ---: | --- |
| 0 | 4 | ASCII `SPPM` |
| 4 | 2 | Payload version `2` (`1` remains readable) |
| 6 | 2 | Header size `36` |
| 8 | 8 | Total file byte length |
| 16 | 4 | CRC-32/IEEE of bytes from offset 36 to end |
| 20 | 2 | Canvas width `640` |
| 22 | 2 | Canvas height `360` |
| 24 | 1 | Layer count `4` |
| 25 | 2 | Palette count `256` |
| 27 | 1 | Playback FPS, 1–30 |
| 28 | 1 | Flags: bit 0 locked, bit 1 allows spin-offs, bit 2 BGM follows animation speed, bit 3 stops after the final frame (clear = loop) |
| 29 | 4 | Frame count, 1–9999 |
| 33 | 1 | Audio track count, 0–4 |
| 34 | 2 | Reserved zero |

Maximum file size is 512 MiB. The CRC protects against accidental damage;
it is not an authentication tag.

## Legacy signed v2 envelope

Legacy files may use the binary/RLE payload with the header version set to `2`,
followed by the four-byte ASCII marker `SPPS` and a 32-byte HMAC-SHA-256 tag.
The tag covers the complete v2 payload, including its header, metadata, frames
and audio. Readers verify the tag in constant time before decoding the payload.
The HMAC key is retained in an encrypted, console-bound `identity-v2-*.bin`
record. This is a legacy local-file integrity scheme; current app saves use the
publicly verifiable Ed25519-signed v3 envelope below. Neither scheme is
Nintendo's signature system or proof of a real-world creator identity.
Readers accept both old v1 and current v2 payloads inside an authenticated
envelope.
`.sppm` is a compact binary encoding with RLE layers, not plaintext and not an
encrypted format.

## Public v3 signatures

Gallery files use the same SPPM payload with its marker set to version `3`,
followed by `SPP3`, public author/original-author/editor identities, and a
64-byte Ed25519 signature. The signed digest covers the complete payload and
all three identities. The server validates the signature and checks each
available FSID against its included public identity. This is self-certifying:
it proves that the included editor key signed those bytes, not that the key
belongs to a Nintendo account or a verified human.

The Ed25519 secret is encrypted at rest with XSalsa20-Poly1305 and a wrapping
key derived from system-specific console material. On CFW, this material is
available to homebrew and is not a hardware-backed, non-exportable secret; a
compromised console can still expose its signing key. The protection is
intended to make a copied SD identity file unusable on an ordinary different
console, not to resist a compromised device.

## Palette and metadata

Immediately after the header are 256 RGBA entries, each four bytes in R, G,
B, A order. The next five fields are UTF-8 strings with `u16 byte length` then
that many bytes: title (at most 256 bytes), description (4096), author name
(128), original author name (128), and last editor name (128). NUL bytes are
forbidden. The reader rejects malformed UTF-8 and preserves valid bytes;
the frontend is responsible for display and editing.

The default drawing palette uses pink at index 6 and purple at index 10.
When reading older SPPMs, the exact opaque legacy colors `(92,224,36)` and
`(26,40,72)` are remapped to `(239,68,133)` and `(132,66,183)`. Palette indices
are unchanged; saving writes the migrated colors back into the SPPM.

Six IDs follow, each exactly 16 uppercase hexadecimal ASCII characters:

1. Author FSID, the current Switchnote creator.
2. Original author FSID, retained through all spin-offs.
3. Last editor FSID.
4. Current note ID, newly allocated for a spin-off.
5. Root note ID, retained through all spin-offs.
6. Parent note ID, the immediate source Switchnote. Sixteen ASCII zeroes encode
   an absent parent on an original note. Zeroes are never a valid allocated ID.

The metadata ends with creation time (`u64` Unix seconds UTC), modification
time (`u64` Unix seconds UTC), and cover frame index (`u32`, zero-based).
Original notes have `currentId == rootId`, no parent, and author FSID equal to
original author FSID. A spin-off must have a new current ID different from its
parent and root IDs. Editing changes the last editor and modification time;
the original author and root ID do not change.

## Frames

Frames appear sequentially. Each frame contains four layer records in A–D
order. A layer record has a codec byte (`1` for RLE), a `u32` compressed byte
length, a `u32` CRC-32/IEEE of the compressed bytes, then the compressed data.
Decoded data is exactly 230,400 row-major `u8` palette indices. The decoder
rejects output beyond that size, truncated packets, unknown codecs, and excess
data. A compressed layer may contain at most 460,800 bytes.

RLE packets have a one-byte command. Bit 7 set means repeat the following
single palette index `(command & 0x7F) + 1` times. Bit 7 clear means copy that
many literal palette indices from the following bytes. Both packet types allow
lengths 1–128. The writer uses repeat packets for runs of at least three.

## Audio

Audio track 0 is background music, starting at frame 0. Tracks 1–3 are sound
effects with frame cues. Tracks are stored in order and each record contains:

| Field | Encoding |
| --- | --- |
| Track index | `u8`, zero-based |
| Channels | `u8`, mono `1` or stereo `2` |
| BGM reference FPS | `u8`, 1–30 for BGM (or 0 to use note speed); zero for SE. Added in payload v2. |
| Sample rate | `u32`, 8000–48000 Hz |
| Name | `u16` byte length + up to 64 UTF-8 bytes |
| Trigger count | `u16` |
| Trigger frames | That many `u16` zero-based frame indices, strictly increasing |
| PCM sample count | `u32`, counts interleaved samples, not stereo pairs |
| PCM CRC | `u32` CRC-32/IEEE of sample bytes |
| PCM | Signed 16-bit little-endian interleaved samples |

BGM has no triggers. A sound effect may be cued multiple times. Every cue must
refer to an existing frame. Total decoded PCM is limited to 32 Mi samples.
To store SE without music, make track 0 an empty BGM entry with a valid rate
and channel count.

With the BGM speed flag set, playback rate is `current FPS / reference FPS`:
changing animation speed changes music tempo and pitch together. With the flag
clear, BGM keeps its imported timing. SE tracks always play at their recorded
speed. The v1 payload defaults to speed-linked BGM.
The playback-loop flag defaults to looping for older files. When set, playback
stops all Switchnote tracks at the end of the final frame; when clear, frame zero
and its BGM/SE cues start together on each loop.

## IDs and spin-offs

Lineage IDs are **64-bit pseudonymous identifiers**, generated as the first
eight HMAC-SHA-256 digest bytes rendered in uppercase hex. The HMAC key is a
32-byte per-install secret generated with the platform cryptographic random
generator and kept in the encrypted console-local identity record. The
message is:

```
ASCII("FlipnoteNX-FSID-v1") || 00 || ASCII(domain) || 00 || 16-byte nonce
```

This historical domain string is retained to keep existing Switchnote identities, signatures, and saved files compatible.

The portable core exposes `deriveFsid(secret, nonce, domain)` so the Switch
frontend can provide randomness through libnx. It uses a fresh random nonce
for each new note ID. Creator FSIDs are the first eight SHA-256 bytes of a
domain-separated Ed25519 public key and a 16-byte one-way device tag. These
values are still 16 hexadecimal characters (64 bits): an FSID is a public
identifier, not a password or proof of authorship.

Gallery coin and comment writes require a random, single-use, 30-second server
challenge signed with the console's Ed25519 key. The server verifies the
signature, FSID/key binding, request method/path/body, and requesting IP. Coin
limits and poster ownership use the full 256-bit signing-key fingerprint,
independent of the shortened FSID and public device tag. Gallery HTTP is LAN-only and does not encrypt public data in
transit; do not expose the development service to the public internet.

Creating a spin-off is an explicit operation. It requires the source to allow
spin-offs and not be locked. It copies frames, palette, and audio; keeps the
root note ID and original author credit; sets parent ID to the source current
ID; allocates a new current ID; sets the new author and last editor; resets
creation/modification time; and makes the child editable. The child may be
saved independently without modifying the parent.

## Safe writing

Signed saves serialize and validate the complete document, write a sibling
temporary file, then replace the target. If the SD filesystem refuses to
replace an existing file by rename, the old file is moved to a unique sibling
backup, the new file is installed, and the old file is restored if installation
fails. Signed loads authenticate the envelope before replacing the caller's
document; legacy loads still validate all bounds, IDs, frame data, CRCs, and
metadata.