oTAPE file format
specification.

§1. Introduction

oTAPE stores one cassette in one file. The file is a portable object you can own, lend, record over, protect, flip and collect, the digital equivalent of a compact cassette in its case.

An .otape file contains:

• the recording on side A and on side B, each one continuous take;
• the cassette's identity and metadata;
• the look of the cassette: plastic shell, label, lettering;
• the paper: J-card cover, spine, back flap and an optional fold-out booklet;
• optional track markers, notes, dedication and history.

§1.1 Design principles

1. A cassette is not a playlist. Each side is one continuous recording. Silence between songs, spoken intros and the click of a pause button are part of the recording.
2. Physical behaviour is preserved. A cassette has a fixed length, two sides that share one tape, a position you reach by winding, and a record tab that can be broken off.
3. The file is the object. It is self-contained and works offline. It never refers to the files that were recorded from.
4. Listening does not change the object. Playback position, ratings and library data stay with the player, not in the file.
5. Open and simple. A ZIP container, one JSON manifest, standard audio and image formats. A developer can write a basic player in an afternoon.
6. Distinctive by design. Every cassette can look unique, either with images in fixed physical proportions or with a compact procedural description any player can draw.

§1.2 Non-goals

oTAPE is not a DRM system, not a streaming format and not a multitrack audio container. It does not describe how a player's user interface must look.

§2. Conventions and terminology

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY and OPTIONAL are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

JSON terms (object, array, string, number, null) are as in RFC 8259. Paths are archive paths (§3.3).

§3. Container

§3.1 ZIP

An .otape file is a ZIP archive (PKWARE APPNOTE 6.3.x).

• Entries MUST use the stored (0) or deflate (8) compression methods.
• Entries MUST NOT be encrypted.
• ZIP64 extensions MAY be used and readers MUST support them.
• File names MUST be UTF-8 (general purpose bit 11 set, or ASCII only).
• Audio and image entries SHOULD be stored, since they are already compressed. A stored entry can be read or streamed in place.
• The archive MUST NOT contain symbolic links. Directory entries are optional and ignored.

§3.2 The mimetype entry

Writers MUST write an entry named mimetype:

• as the first entry of the archive,
• stored (no compression), with no extra field,
• containing exactly the 30 ASCII bytes application/vnd.otape.cassette, with no line break.

This puts the media type at a fixed offset (byte 38) of the file, so tools can recognise an oTAPE file without unzipping it. EPUB and OpenDocument use the same technique. Readers SHOULD NOT reject a file because mimetype is missing or not first. The manifest is authoritative.

§3.3 Paths

Every path in the manifest refers to an entry in the same archive and MUST:

• be relative (no leading /), use / as separator and contain no \;
• contain no . or .. segment;
• not be mimetype or manifest.json.

Paths are case-sensitive. Writers SHOULD use lowercase ASCII paths.

§3.4 Layout

example.otape
├── mimetype                    REQUIRED  first entry, stored
├── manifest.json               REQUIRED  the cassette (§6)
├── audio/
│   ├── side-a.m4a              REQUIRED if side A has been recorded on
│   └── side-b.m4a              REQUIRED if side B has been recorded on
├── artwork/                    OPTIONAL  images (§12)
│   ├── cassette-face-a.png
│   ├── cassette-face-b.png
│   ├── label-a.png
│   ├── label-b.png
│   ├── jcard-front.png         (or .jpg)
│   ├── jcard-spine.png
│   ├── jcard-flap.png
│   ├── booklet-01.png …        booklet panels in reading order
│   └── thumbnail.png
├── docs/                       OPTIONAL  booklet.html, notes.md (§12.7)
└── extras/                     OPTIONAL  implementation data (§15.3)

The names under audio/ and artwork/ are RECOMMENDED names. Readers MUST use the paths given in the manifest and MUST NOT guess a file from its name.

§3.5 Limits

Readers MAY refuse files that exceed these limits.

§4. Identification

Applications that own the format SHOULD register the extension with their platform's document-type mechanism. On Apple platforms that is UTExportedTypeDeclarations plus CFBundleDocumentTypes.

§5. Cassette model

§5.1 Cassette types

For the standard types side_length_seconds MUST equal the value in the table. Readers MUST reject a mismatch. A custom cassette is labelled like a real one, with its total length in minutes rounded: C + round(2 × side_length_seconds / 60), e.g. 37 minutes per side → C74.

§5.2 Identity

The id is an identity, not a protection mechanism. Two copies of a file are the same cassette.

§5.3 Timeline

All positions and lengths in a cassette, including recorded_frames, marker frame, history start_frame and end_frame, are integers on one timeline:

• cassette.timeline_rate is 44100 or 48000 frames per second. Default: 44100.
• The side length in frames is side_length_seconds × timeline_rate.

Using integer frames instead of seconds makes positions exact. A recording and the silence after it line up to the sample.

§5.4 Head position and flipping

Both sides share one physical tape. A head position p frames into side A is the same piece of tape as L − p frames into side B, where L is the side length in frames.

Players that simulate flipping SHOULD apply this mapping: at the end of side A you flip to the start of side B. Players MAY instead keep independent positions per side if they don't simulate the tape physically.

§5.5 Blank tape

Any part of a side that has never been recorded is blank tape and plays as silence. This includes every frame from recorded_frames to the end of the side, and all of a side whose audio is null. Players MAY render blank tape with a faint tape hiss.

§6. Manifest

manifest.json is a UTF-8 JSON document without a byte-order mark. Its root is an object.

§6.1 Top level

All keys use snake_case. Side keys are the uppercase letters "A" and "B" everywhere they appear.

§6.2 cassette

§6.3 Example

A minimal valid manifest (blank C60):

{
  "format": "oTAPE",
  "format_version": "1.0",
  "cassette": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Night Drive",
    "type": "C60",
    "side_length_seconds": 1800,
    "created_at": "2026-10-28T22:00:00Z"
  },
  "sides": {
    "A": { "write_protect": "intact", "audio": null },
    "B": { "write_protect": "intact", "audio": null }
  }
}

A complete example with every field is in examples/manifests/manifest-full.json. Complete example cassettes are in examples/files/.

§7. Sides and audio

§7.1 Side object

¹ Writers MUST write the key, using null for a blank side. Readers MUST treat a missing audio like null.

§7.2 Audio object

An audio object with recorded_frames = 0 is equivalent to null. A side has at most one audio file. The audio is one continuous recording from frame 0 to recorded_frames.

§7.3 Codecs

Rules for audio files:

• AAC-LC streams SHOULD be encoded at ≥ 192 kb/s for stereo. 256 kb/s is recommended.
• AAC encoder delay and padding MUST be signalled with an MP4 edit list or iTunSMPB, so the decoded length is exact.
• Readers MUST treat the decoded audio as exactly recorded_frames long. Excess samples are cut off. If the file decodes shorter, the rest is silence.
• If sample_rate differs from timeline_rate, the reader resamples to the timeline.
• A reader that meets an optional codec it can't decode MUST still open the cassette, report that side as unplayable, and keep the file intact on re-save.

§7.4 Track markers

Markers name places on a side. They are informative: the side stays one continuous recording.

Markers SHOULD be sorted by frame. Players MAY show the marker nearest before the head, e.g. "now playing". Players SHOULD NOT offer to jump to a marker instantly. Reaching a position by winding is part of the medium. A player that does offer jumping SHOULD animate it as winding.

§7.5 Playback

• A player plays a side from the head position at real-time speed.
• Positions from recorded_frames to the side end are blank tape (§5.5).
• At the end of a side, playback stops. A player MAY simulate auto-reverse.
• FAST FORWARD and REWIND move the head at a multiple of real-time speed and SHOULD take noticeable time. A full C60 side takes 1 to 2 minutes on a real deck.

§8. Write protection

A real cassette has one record tab per side. Breaking it off stops a deck from recording that side. Covering the hole with tape makes the side recordable again. oTAPE models this as a physical property of the medium.

This is not DRM. It protects a finished tape from accidental recording, as on a real cassette. Anyone can tape over the hole.

§8.1 States

§8.2 Transitions

intact ──break off──▶ broken ──cover with tape──▶ taped_over
                         ▲                            │
                         └────── remove the tape ─────┘

A broken tab never becomes intact again. Writers MUST NOT change broken or taped_over to intact. Every change SHOULD be logged as a write_protect_changed history event (§13).

§8.3 Behaviour

A conforming recorder:

• MUST refuse to record on a side whose state is broken;
• MUST offer an explicit "cover with tape" action that sets taped_over;
• SHOULD show the tab state, e.g. on the cassette's top edge.

§9. Recording

oTAPE files are produced by recording in real time. The format doesn't require that, but its rules follow from it.

• Overwrite in place. Recording at head position p for n frames replaces frames p … p + n − 1 of that side. Everything else is unchanged.
• High-water mark. After recording, recorded_frames = max(old value, p + n). It never shrinks, except through an erased event (§13.2) that sets it to 0.
• Silence is recorded. Pausing the source while the tape keeps running records silence.
• End of side. Recording stops at the end of the side. Nothing is carried over to the other side.
• Markers. A recording pass over [p, p + n) removes the markers in that range. The pass MAY add new ones.
• Writing the file. Writers SHOULD re-encode only sides that changed, and SHOULD write to a temporary file and rename it over the original, so a failed save never leaves a damaged cassette.

§10. Appearance

appearance describes the cassette in a compact form that any player can draw. A cassette with no images still looks like itself. Images (§12) replace the drawn parts where present.

§10.1 Structure

"appearance": {
  "preset": "smoke",
  "shell": { "color": "#3A3F478C", "finish": "transparent" },
  "label": { "style": "stripes", "paper": "#FAFAF5", "ink": "#202020", "accent": "#E4572E", "font": "pen" }
}

Defaults when absent: shell #1B1B1D opaque, paper #F3EEDC, ink #1D2B53, accent #C8102E, style ruled, font marker.

§10.2 Colours

Colours are sRGB strings #RRGGBB or #RRGGBBAA (hex, case-insensitive). Alpha FF is opaque.

§10.3 Label styles

Unknown styles MUST be drawn as plain.

§10.4 Procedural label layout

All values are in label coordinates (mm from the label's top-left corner). See §12.5 and templates/label.svg.

Text that doesn't fit SHOULD be truncated with an ellipsis rather than shrunk below 60 %.

§10.5 Lettering (font roles)

oTAPE names a role rather than a typeface, so every platform can draw it with a font it has.

Unknown roles MUST be drawn as sans.

§11. J-card and case

The J-card is the folded paper insert in the case. From outside you see the front, the spine and, folded behind, the back flap.

§11.1 Structure

"jcard": {
  "card_color": "#1C1033",
  "ink": "#FFE8A3",
  "font": "stencil",
  "front": { "title": "Night Drive", "subtitle": "a mixtape for the A4" },
  "spine": { "text": "NIGHT DRIVE · 2026" },
  "flap": { "text": "Dolby B · Type II · Jan Osio" },
  "tracklist": { "A": ["Intro", "Midnight City"], "B": ["Sunrise"] },
  "dedication": "For everyone still awake."
}

The printed tracklist is what the creator wrote on the card. It is independent of the markers (§7.4). Writers MAY fill it from the markers.

§11.2 Procedural J-card layout

§11.3 Reading direction

The spine and flap are stored and described upright: the panel is portrait, with its top at the top of the front cover. Their text is rotated 90° clockwise and reads top to bottom, so it reads correctly with the case lying front-up and the spine towards you. Creators supplying images SHOULD follow this.

§11.4 Case

The standard case is 109.0 × 70.0 × 17.0 mm and the cassette is 100.4 × 63.8 × 12.0 mm. Players that draw the case in 3D SHOULD use these sizes. The J-card front is seen through the lid, and the spine runs along the long edge.

§12. Artwork

§12.1 General rules

• Formats: PNG (REQUIRED support, may have alpha) and JPEG (REQUIRED support, opaque art only). The file extension SHOULD match the format (.png, .jpg).
• Colour: sRGB. Images in other colour spaces SHOULD be converted when written.
• Trim size, no bleed. The image edge is the paper edge. Print production with bleed is outside this specification.
• Resolution is given per millimetre:
  • recommended 24 px/mm (≈ 610 ppi);
  • minimum 12 px/mm (≈ 305 ppi). Writers SHOULD NOT store images below it.
• Proportions are fixed. The image's aspect ratio (width ÷ height) MUST be within ±1 % of the slot's ratio. Readers MUST draw a slot image stretched exactly to the slot's physical rectangle. Writers MUST reject or crop images with wrong proportions.
• Images are optional. Without an image, a slot is drawn procedurally (§10, §11).

§12.2 Slots

Pixel sizes are the physical size × px/mm, rounded to the nearest integer.

The thumbnail is a square preview for file browsers, Quick Look and library views: the cassette (and/or case) on a transparent background. Writers SHOULD regenerate it on save so it shows the current look.

Unknown slot names MAY appear in artwork. Readers ignore them, and writers keep them (§15.2).

§12.3 Layering

A player draws the cassette face from back to front:

1. Mechanism, drawn by the player and animated: tape packs (radius from the head position, Appendix B.3), the tape path along the head opening, and the white drive hubs, which turn with the reels.
2. Shell face: cassette_face_a/_b, or the procedural shell (§10.1). The window and both hub holes are cut out.
3. Label: label_a/_b, or the procedural label (§10.4). The keep-out zone (§12.5) is cut out.
4. Glass: a subtle reflection over the window. Optional.

Because the mechanism is underneath, images MUST be transparent wherever the reels should show. A transparent (finish: transparent) shell image uses partial alpha so the tape packs show through the plastic.

§12.4 Cassette face

Coordinates in mm from the top-left of the face, cassette upright, head opening at the bottom:

Side B's face has the same layout. The cassette is turned over, not mirrored.

§12.5 Label

• Size 89.0 × 42.0 mm, corner radius 2.0. It sits at (5.7, 3.5) on the face.
• Keep-out zone, which MUST be transparent: the window and both hub holes, grown by 0.5 mm. In label coordinates that is the window rectangle x 24.0–65.0, y 17.5–30.5, plus circles of Ø 18.0 around (23.3, 24.0) and (65.7, 24.0). Players cut this zone out whatever the image contains.
• Safe area: 2.0 mm inset. Keep lettering inside it.
• Lettering zones of the procedural label: §10.4.

§12.6 J-card panels

Unfolded outside, left to right: flap 15.9 | spine 12.7 | front 63.5, all 101.6 mm high, 92.1 mm wide in total. Each panel is a separate image.

• Safe area: 3.0 mm on the front, 1.5 mm on the spine and flap.
• Spine and flap images are stored upright (portrait) with their text reading top to bottom (§11.3).

§12.7 Booklet and documents

"booklet": {
  "panels": ["artwork/booklet-01.png", "artwork/booklet-02.png"],
  "html": "docs/booklet.html",
  "notes": "docs/notes.md"
}

• panels: fold-out panels in reading order, each 63.5 × 101.6 mm (1524 × 2438 px). They unfold to the right of the front cover. Panel 1 is usually the inside of the cover.
• html: an optional HTML booklet for liner notes, photos and lyrics. It MUST follow the oTAPE booklet profile:
  • HTML5, UTF-8, a single file;
  • no scripts: no <script>, no event-handler attributes, no javascript: URLs;
  • no forms, <iframe>, <object> or <embed>;
  • only relative URLs to entries in the same archive (images, CSS), with no network access;
  • designed for a portrait page of 63.5 mm × 101.6 mm, scrolling vertically.

  Readers that display it MUST do so in a sandbox with scripts and network disabled. Readers MAY ignore it.

• notes: longer notes as CommonMark Markdown.

If both panels and html exist, the panels are the canonical printed look and the HTML is an alternate reading view.

§12.8 Templates

SVG templates at 1:1 millimetre scale are in templates/: cassette-face.svg, label.svg, jcard-outside.svg and booklet-panel.svg. They import into vector tools at real size.

Every dimension in this section is also published as JSON in geometry/otape-geometry-1.0.json, for implementations that draw cassettes. The templates are generated from that file by tools/make_templates.py. If the JSON and this text ever disagree, this text is normative.

§13. History

history records the cassette's life as a collector's object. It is optional, and readers MUST NOT need it to play the cassette.

§13.1 Event object

Events are in chronological order, and writers append to the end.

§13.2 Event types

source is one of file, line, radio, microphone, dub or generated. source_format is free text, e.g. mp3.

Readers MUST ignore event types they don't know, and writers MUST keep them (§15.2).

§14. Medium state and local state

Playing a cassette MUST NOT modify the file. Players SHOULD remember the side and head position per cassette.id, so a cassette put back into the deck resumes where it was, the way a real tape stays wound where you left it.

§15. Versioning and extensibility

§15.1 Versions

format_version is "MAJOR.MINOR".

• Minor versions only add optional fields, values or slots. A 1.x reader MUST read every 1.y file, ignoring what it doesn't understand.
• Major versions may change meaning. Readers MUST refuse a major version they don't support, and SHOULD say that the file needs a newer application.
• Writers MUST write the lowest version whose features they use, and MUST NOT claim a version they don't implement.

§15.2 Preservation

Unknown fields, unknown slots, unknown history events and unknown archive entries MUST be ignored by readers. Writers modifying an existing cassette MUST preserve them unchanged, unless the user removes them explicitly. This lets cassettes pass between applications without losing anything.

§15.3 Extensions

Implementation-specific data goes in extensions, keyed by a reverse-DNS identifier the implementer controls:

"extensions": { "org.example.player": { "shelf_position": 12 } }

Files go under extras/<identifier>/…. Extensions MUST NOT change the meaning of standard fields.

§16. Conformance

§16.1 Reader (validator)

A conforming reader:

1. opens the ZIP container (§3), checking paths (§3.3) and limits (§3.5);
2. checks format = oTAPE and that it supports the major version;
3. validates the required fields: cassette.id, type with matching side_length_seconds, created_at, and both sides with a valid write_protect;
4. for each side with audio, checks that file exists and that recorded_frames ≤ the side length in frames;
5. rejects the file if any of the above fails, naming the reason.

The JSON Schema schema/otape-manifest-1.0.schema.json covers the structural part. Rules spanning several fields, such as recorded_frames against the side length or entries existing in the archive, need code. tools/otape_validate.py implements all of them, together with the artwork and container checks.

§16.2 Player

A conforming player is a reader that additionally:

• plays both sides from aac-lc audio with exact length (§7.3), treating blank tape as silence;
• shows at least the title, type, side and position;
• draws the artwork it supports, falling back to appearance or a neutral cassette;
• does not modify the file while playing (§14).

§16.3 Recorder

A conforming recorder is a player that additionally:

• records over a side in place and updates recorded_frames (§9);
• refuses to record on broken sides and offers "cover with tape" (§8);
• writes mimetype first (§3.2), aac-lc audio and a valid manifest;
• preserves unknown data (§15.2).

§16.4 Editor

A conforming editor changes metadata, appearance, J-card or artwork without re-encoding audio, enforces artwork proportions (§12.1) and preserves unknown data.

§17. Security considerations

• Path traversal. Reject .., absolute paths and backslashes (§3.3). Never extract outside a private directory.
• Decompression bombs. Limit the total uncompressed size and the compression ratio. Stream large entries.
• Images. Enforce the pixel limits before decoding (§3.5).
• HTML booklets are untrusted content. Render them only in a sandbox with scripts and network disabled (§12.7).
• Privacy. History and metadata can contain names, places and dates. Applications SHOULD let users see and remove them before sharing a cassette.
• No DRM. write_protect and id provide no security and must not be relied on as such.

§18. Reference material

§Appendix A: Changes from the 1.0 draft

The first draft of this specification was reviewed against a working recorder. These inconsistencies were resolved for 1.0:

§Appendix B: Geometry reference

All values below, and those of §12, are also in geometry/otape-geometry-1.0.json.

§B.1 Summary of physical sizes (mm)

§B.2 Pixel sizes

§B.3 Reels and tape packs

For realistic reels, players MAY use this model (all lengths in cm):

• tape speed v = 4.76 cm/s; tape length on a side ℓ = v × side_length_seconds;
• empty reel (hub) radius r₀ = 1.1 cm;
• tape thickness t: 18 µm for sides up to 35 minutes (C46, C60), 12 µm up to 50 minutes (C90), 9 µm above that (C120);
• with x the tape already wound onto the take-up reel (x = v × head seconds):
  • take-up pack radius r = √(r₀*² + *x·t/π)
  • supply pack radius R = √(r₀*² + (*ℓ − x)·t/π)
  • revolutions of the take-up reel since the start of the side = (r − r₀) / t, which also drives a realistic three-digit mechanical counter.

On a C60 this gives a full pack radius of about 2.47 cm. The take-up reel turns fast at first and slows down as it fills.

§Appendix C: Reading an oTAPE file step by step

open ZIP
  └ if first entry is "mimetype": expect "application/vnd.otape.cassette" (informative)
read manifest.json  → JSON object (≤ 1 MiB)
  ├ format == "oTAPE"                    else: not an oTAPE file
  ├ major(format_version) == 1           else: needs newer app
  ├ cassette.id is UUID
  ├ (type, side_length_seconds) valid    (§5.1)
  ├ rate = cassette.timeline_rate ?? 44100
  └ for side in A, B:
       write_protect ∈ {intact, broken, taped_over}
       if audio != null and audio.recorded_frames > 0:
           path safe and present in archive
           recorded_frames ≤ side_length_seconds × rate
           decode, resample to rate if needed, trim/pad to recorded_frames
       else: side is blank tape
draw: appearance + artwork (§10, §12), jcard (§11)
restore local head position for cassette.id (§14)