Skip to content

The show file

One folder per show. Audio as ordinary files; everything else in a single SQLite database beside them. Copy the folder to a USB stick and the show travels complete — episodes, transcripts, chapters, edits, custom fields, and which step of the workflow you had reached.

Ondes Courtes/
├── ondes-courtes.podlibre     one SQLite file: the whole model
├── artwork.jpg
└── episodes/
    └── 14-le-son-du-silence/
        ├── camille.wav        sources stay as files; the database points at them
        ├── invite.wav
        ├── musique.flac
        └── export.mp3

Audio is not stored in the database. A show is tens of gigabytes of audio and a few megabytes of everything else, and the two want different treatment: files for the audio, so any other tool can read it and a backup can deduplicate it; a transaction log for the rest, so an interrupted edit never leaves half a change behind.

The fixed part of the model

Table Holds
show One row. The podcast itself.
episode One row per episode.
track A lane in the editor: a microphone, the music bed.
clip A piece of audio on a track, with its source file and position.
chapter Title, start, optional image and link.
speaker A voice, named once per episode by the user.
segment A span of transcript: start, end, speaker, text.
dictionary_rule The user's own corrections, applied to a transcript without a model.
bookmark Somewhere to come back to: an episode, or a moment inside one.
field_def, field_value Everything else — see below.
workflow_state Which workflow this show uses, and any the user has made.
mark Steps the user ticked off by hand, for work that leaves no other trace.
schema_version One integer, and the migrations that read it.

Bookmarks are here, in the show, rather than in Podlibre's own settings. A note saying "pickup to re-record" is about the work, not about the machine it was written on, so it travels when the show is copied to another one. A bookmark whose at_ms is null means the episode; a bookmark with one means a moment inside it.

The variable part

Almost nothing about podcast metadata is fixed. iTunes defines a set of tags, Podcasting 2.0 defines more each year, and a plugin may invent one tomorrow. So none of them are columns.

A field definition is a row describing a field: its key, what it attaches to, its type, its label, where it goes on the way out, and whether other plugins may read it.

field_def(key, target, type, choices, label_key, rss_tag, id3_frame, owner, shared, stored)
field_value(key, target, target_id, value)

target is show or episode, and it is half the primary key of both tables: a show and an episode may each have a title, and they are not the same field.

Three layers, one mechanism:

Layer Examples Comes from
Base title, author, explicit, season The iTunes podcast DTD, shipped — 27 fields
Extended transcript, chapters_url, person, funding Podcasting 2.0, shipped — 11 fields
Added notes_html, mood A plugin, at load time

Keys, not tags: the Podcasting 2.0 field keyed transcript is what goes out as podcast:transcript, and the tag is in the definition rather than in the name.

None of the three is special-cased in code. Adding a field is inserting a row, and the third layer needs no release of Podlibre. Two fields are the exception: show.title and episode.title really are columns, because the library sorts and lists by them constantly, and stored names the column so that reading them still goes through the same call.

The full schema, with every column and a worked example of all three layers on one episode, is in the data model.

Because a definition carries its own RSS tag and ID3 frame, an exporter written before a field existed still emits it correctly. And a field marked shared is readable by every plugin: the show-notes writer declares notes_html, the Castopod publisher reads it, and neither needs to know the other exists.

Who may write

One Show object owns the connection and serialises every write, so two things writing at once -- the window and a plugin's thread -- cannot interleave a half-finished edit. Plugins use the same object rather than opening the file themselves, which is what makes that promise hold.

That serialising is also where a subtle bug lived: a write that released the lock before the caller had read its result would hand back rows another thread had already moved on from. It failed about one run in three, and the tests that catch it are in tests/test_show.py.

Moving a show

Nothing in the database holds an absolute path. A clip points at episodes/14-…/camille.wav relative to the show folder, so the folder can be moved, renamed, copied to another operating system, or kept in a sync folder, and still open.