Skip to content

Export Format Specification v0.11.

This document describes the bundle TellSophie builds for every export: the final export sent when a space closes or if we shut down, and an export you ask for. Both are built automatically, in this format. Version 0.11 is provisional. A few fields specified in earlier versions are not written yet; the section “Specified, not yet written” lists them.

You ask for an export in the app, under Plan & billing; the child’s parent or the person who pays for the space can ask. The build starts at once, and the download link is emailed to the address on your account, normally within a day. One copy can be requested per space per day. If you cannot reach the app, email support from the address on the account and they start the build for you. Our commitment is the link within five business days of your request. An export you ask for leaves out recordings set to stay closed until a later date.

We publish the spec so the export commitment is inspectable. Any future tool, service, or self-hosted player can read TellSophie collections without our cooperation by following this spec.

Related: Trust commitments.

Bundle structure.

The export is a single .zip file. Top-level layout:

A recording’s <name> is <date>_<who>_<short id>:

File names are for people. A tool should match files through manifest.json rather than by parsing names.

An example, with made-up names and ids:

README.txt
manifest.json
recordings/2026-03-14_Nana_1a2b3c4d.mp4
recordings/2026-03-14_Nana_1a2b3c4d.json
recordings/2026-03-15_Auntie-Rae_5e6f7a8b.m4a
recordings/2026-03-15_Auntie-Rae_5e6f7a8b.json
transcripts/2026-03-14_Nana_1a2b3c4d.txt
annual_letters/year-1.txt
annual_letters/year-1.json
annual_reels/year-1.mp4
annual_reels/year-1.pdf
private/recordings/2026-04-02_Alex_9c0d1e2f.m4a
private/recordings/2026-04-02_Alex_9c0d1e2f.json

Who gets what.

An export holds the recordings shared with the family, plus the private recordings made by the person who receives it.

manifest.json.

Top-level fields:

Each recordings entry:

An example entry, with made-up data:

{
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "media_type": "video",
  "recorded_at": "2026-03-14T18:22:05.123Z",
  "duration_seconds": 58,
  "format": "mp4",
  "contributor_display_name": "Nana",
  "prompt_text": "What made you laugh today?",
  "media_path": "recordings/2026-03-14_Nana_1a2b3c4d.mp4",
  "transcript_path": "transcripts/2026-03-14_Nana_1a2b3c4d.txt",
  "private": false,
  "sealed": false
}

Details files.

Each recording and letter has a details file beside it, with the same base name and a .json extension. It holds schema_version and the same fields as that recording’s recordings entry in manifest.json, so one file can be read on its own. Films and photo books have no details file.

A recording that is not in the bundle has no details file, no manifest.json entry and no line in README.txt.

README.txt.

A plain-text guide at the bundle root, written for the family rather than for tools. It says what the bundle is and when it was made, explains each folder the bundle holds, says how to play the files, notes that dates are in UTC, and suggests keeping a second copy somewhere safe. It ends with one line per recording and letter, in the order recorded: the date written out, who made it, the prompt (or “No prompt”, or “A yearly letter”), and the file’s path. A tool should read manifest.json instead; the README’s wording can change between builds.

Specified, not yet written.

Version 0.10 specified these fields. The export does not write them, so a tool reading a bundle today should not expect them.

Version 0.10 also specified fields that the shipped format replaces. They will not be written under these names:

Standards used.

What changes from v0.11 to v1.0.

Version 1.0 will lock these additions:

Questions.

If you are building a tool against this spec and find an ambiguity, email privacy@tellsophie.com. We will publish clarifications on this page.