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:
README.txt— a plain-language guide to the bundle, followed by one line for every recording in it.manifest.json— bundle metadata, the details of every recording, and a listing of every recording, letter, film and photo book in the bundle with a SHA-256 hash for each.recordings/— one media file per recording shared with the family:recordings/<name>.m4afor audio,recordings/<name>.mp4for video. Beside each one is a details file with the same base name,recordings/<name>.json.transcripts/— plaintext transcripts attranscripts/<name>.txt, one per recording with a transcript. Same<name>as the media file, so a tool matches a transcript to its media by base filename.annual_letters/— each Annual Letter as plaintext atannual_letters/year-<N>.txt, where<N>is the child’s year of life, with its details file atannual_letters/year-<N>.json. A letter not linked to a year, or a second letter linked to the same year, is written asannual_letters/letter-<id>.txt(details atannual_letters/letter-<id>.json), where<id>is the letter’s UUID.annual_reels/— a published year-end film atannual_reels/year-<N>.mp4and a published photo book atannual_reels/year-<N>.pdf, for each year that has one, where the space has these.private/— your own private recordings, in the same layout as the top level (private/recordings/,private/transcripts/,private/annual_letters/).sealed/— final export only. Recordings set to stay closed until a later date, in the same layout. Your own sealed private recordings are underprivate/sealed/.
A recording’s <name> is <date>_<who>_<short id>:
<date>is the UTC calendar date it was recorded, asYYYY-MM-DD(undatedif the date is not known). Depending on where it was made, this can be the day before or after the local date.<who>is the recording’scontributor_display_name(see below), so it can be a relationship such asGrandparent, orA-guestorSomeone-in-the-familywhen no name is on record. It is reduced to ASCII letters, digits and hyphens, at most 40 characters: accents are dropped (Zoë becomesZoe), a few letters are spelled out (ß becomesss), and any run of other characters, such as spaces, punctuation or emoji, becomes a single hyphen, with none at the start or end. If nothing is left (a name written only in emoji or a non-Latin script, for example), it isfamily, orguestfor a guest’s recording. The fullcontributor_display_nameis in the details file,manifest.jsonandREADME.txt.<short id>is the first 8 hex digits of the recording’s UUID. Only when the date, the person and the short id all match another recording in the same folder (ignoring case) does the later one, in the order recorded, take its full UUID instead.
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.
- If you receive an export, your own private recordings are in it, under
private/. An export goes to the parent or the person who pays for the space, not to every family member. - Other people’s private recordings are not. A private recording someone else made is never in your copy, and yours is never in theirs. Only the person who made a private recording can play it, and that holds for the parent who runs the space too.
- A private recording with no maker on record is in no one’s copy. That covers a guest’s recording the parent has not shared with the family (guest recordings start private), and one made by someone whose account was deleted.
- Sealed recordings depend on the kind of export. A final export, the one sent when a space closes or if we shut down, includes recordings set to stay closed until a later date, under
sealed/, orprivate/sealed/for the recipient’s own. An export you request is meant to leave them out. - Year-end films and photo books, where a space has them, use shared recordings only. A year-end film or photo book is included only if every recording in it was shared with the family and can still be played.
- Removed and held recordings are left out. A recording that was removed, or that safety screening has not cleared, is not in any export.
manifest.json.
Top-level fields:
schema_version: string. The export-format spec version this bundle conforms to:"0.11".archive_id: string. UUID of the child’s space. Stable across exports.job_id: string. UUID. Unique per export.generated_at: string. ISO 8601 UTC timestamp of when the bundle was built.child_display_name: string or null. The child’s name as set in the space when the bundle was built; null if it could not be found.recording_count: integer. Recordings and letters in the bundle, including those underprivate/andsealed/.artifact_count: integer. Year-end films and photo books in the bundle.files: array of objects, one per recording, letter, film or photo book, withid,path(relative to the bundle root, including anyprivate/orsealed/prefix),media_type(one ofaudio,video,text_letter,annual_reel,photo_book), andsha256(hex digest of the file’s bytes). Transcripts, details files,README.txtandmanifest.jsonitself are not listed; a transcript and a details file share their recording’sid. For a film or photo book,idis the year’s id; that year’s film and photo book share it.recordings: array of objects, one per recording and letter in the bundle, in the order they were recorded. Fields below.
Each recordings entry:
id: string. The recording’s UUID; the sameidas itsfilesentry.media_type: string. One ofvideo,audio,text_letter.recorded_at: string or null. ISO 8601 UTC timestamp of when it was recorded; null only if the stored date could not be read.duration_seconds: integer or null. Length in whole seconds; null when no length is stored.format: string. The written file’s extension:mp4(video),m4a(audio) ortxt(letter).contributor_display_name: string, never null. Who made it, as the family knows them: their display name, else what the child calls them, else their relationship (for exampleGrandparent). For a guest, the name they gave, elseA guest. With no one on record,Someone in the family.prompt_text: string or null. The prompt the recording answered, as it was shown. Present only when the prompt was written for the person who made the recording; otherwise null, including for a guest’s recording and when there was no prompt.media_path: string. Path of the media file or letter, relative to the bundle root.transcript_path: string or null. Path of its transcript; null when none was written. A letter’s text is the letter file itself, so for a letter this is null.private: boolean. True for the recipient’s own private recording, underprivate/.sealed: boolean. True for a recording set to stay closed until a later date, undersealed/orprivate/sealed/. Only a final export has these.
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.
timezone: string. IANA tz database name (e.g.America/Los_Angeles). No time zone is recorded for a space today, so every date in the bundle is UTC.contributor_id: string. A stable id for the person who made a recording, the same across their recordings. Today a recording carries onlycontributor_display_name.prompt_id: string. A stable id for the prompt a recording answered. Today a recording carries onlyprompt_text.
Version 0.10 also specified fields that the shipped format replaces. They will not be written under these names:
bundle_id(ULID) andexported_at: the per-export id isjob_id(UUID) and the build time isgenerated_at.child_id(ULID): the stable id isarchive_id(UUID), the id of the child’s space.- On each recording,
created_atis nowrecorded_at,duration_ms(milliseconds) is nowduration_seconds(whole seconds), andformatis a file extension (mp4,m4a,txt) instead ofaudio/m4aorvideo/mp4. - The details file is named like its media file,
recordings/<name>.json, rather thanrecordings/<id>.json.
Standards used.
- Container format: ZIP per APPNOTE.txt 6.3.x.
- Audio encoding: AAC-LC, 96 kbps, in MPEG-4 container (
.m4a). - Video encoding: H.264, 8-bit 4:2:0, scaled to 720 pixels tall at 4 Mbps (1080 pixels tall at 6 Mbps if the space had high-quality video on when it was recorded), width kept in proportion. AAC-LC audio track at 128 kbps. MPEG-4 container (
.mp4). - Year-end films: H.264 in MPEG-4 container (
.mp4). Photo books: PDF. - Transcripts, letters and
README.txt: UTF-8 plaintext, no timestamps in v0.11 (timestamped transcripts are planned for v1.0).manifest.jsonand details files: UTF-8 JSON. - File names: ASCII letters, digits, hyphens and underscores, plus the folder and extension.
- IDs: UUID per RFC 9562.
- Integrity: SHA-256, lowercase hex.
- Timestamps: ISO 8601 UTC with millisecond precision. Dates in file names are UTC calendar dates.
What changes from v0.11 to v1.0.
Version 1.0 will lock these additions:
transcript_segmentsarray in the details file with per-utterance timestamps.- A
signature.txtfile at the bundle root carrying a detached cryptographic signature overmanifest.jsonso a future tool can verify the bundle was emitted by TellSophie infrastructure (independent of the bundle’s file integrity). - A
prompts.jsoncatalog snapshot embedded in the bundle so a future tool does not need network access to resolve prompts, once recordings carry aprompt_id.
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.