The .storyflow package format

Schema version 1 · a proposal under development; it may change before release 1.0

A .storyflow package moves a whole Tellavio project between devices: script, recorded takes, imported sounds and editing settings. This description is for the team and for future integrations.

Archive layout

It is a plain ZIP archive. The .storyflow extension identifies the format, not encryption: the contents are not encrypted. The assets/ folder holds the unmodified audio originals; each file name is the asset ID.

project.storyflow   (ZIP)
├── manifest.json
└── assets/
    ├── <assetId>.wav
    ├── <assetId>.m4a
    └── <assetId>.mp3

manifest.json

The manifest describes the package and contains project data without absolute paths. Editing times are counted in samples at 48 kHz.

{
  "schemaVersion": 1,
  "app": { "name": "StoryFlow", "version": "0.1.0" },
  "projectId": "…",
  "sourceRevision": 42,
  "createdAt": "2026-10-05T12:00:00Z",
  "completeness": "all_takes",
  "assets": [
    { "path": "assets/9f1c….wav", "sha256": "…", "bytes": 1234567, "mime": "audio/wav" }
  ],
  "project": { "…": "…" },
  "chapters": [], "segments": [], "takes": [], "markers": [], "clips": [],
  "templateSnapshot": {}
}

Manifest fields and their meaning
Field	Meaning
`schemaVersion`	Package schema version (integer). Currently 1.
`app`	Name and version of the app that created the package.
`projectId`	Project ID on the source device. By default, import creates a new project with a new ID.
`sourceRevision`	Project revision at the time the package was exported.
`createdAt`	Package creation time (ISO 8601, UTC).
`completeness`	all_takes: every take, full history; used_only: only takes used in the edit, which the app labels as an incomplete copy of the history.
`assets`	List of files in assets/: relative path, SHA-256 checksum, size in bytes and MIME type.
`project`	Project data (title, settings) without absolute paths.
`chapters, segments, takes, markers, clips`	Chapters, parts (segments), takes, markers and edit clips.
`templateSnapshot`	Snapshot of the sound template used in the project, so the package does not depend on templates on the target device.

Import rules

The archive is unpacked to a temporary area and verified before anything reaches your projects.
Entries whose path contains .., absolute paths and duplicate paths are rejected.
There is a limit on unpacked size and number of entries (zip bomb protection).
The SHA-256 checksum and size of every asset must match the manifest.
A package with a newer schemaVersion than the app supports is rejected as a whole, never partially.
A missing or damaged asset is listed in a report. It is never replaced with silence.
By default a package is imported as a new copy of the project. Replacing an existing project requires confirmation and keeps its previous version.
The project is committed in a single transaction: all or nothing.

Privacy

A package may contain failed takes and private notes. Before sharing, the app shows what the package will include. A finished audio export (M4A, WAV) is different from a package: it contains no notes or takes.

Versioning

schemaVersion changes only when the new app version still imports every older package. Questions about the format and integrations: kontakt@tellavio.com.