The workflow engine¶
Making a podcast is a sequence of activities, and Podlibre models that sequence rather than presenting a drawer of tools. This is the part of the application the project description calls the core system.
Activities¶
An activity is one thing a podcaster does.
| Field | Meaning |
|---|---|
id |
Stable identifier. Keys its strings and its completion marks, so it never changes once released. |
scope |
application, show, or episode — which level of the work it belongs to. |
phase |
Which group it sits in, so a long workflow stays readable. |
icon |
The mark it is drawn with. One naming none is drawn with a generic mark rather than a blank, so a plugin inventing a step does not have to learn the name of a glyph to look like everything around it. |
title, hint |
Already translated, for an activity a plugin declares. The shipped ones leave both unset and are named through their keys, because Podlibre's own catalogue cannot hold keys for extensions it has never heard of. |
provides |
Which plugins serve it. The shipped activities name none: an engine with a favourite plugin is not an engine. |
shell |
Whether Podlibre itself serves it, with no plugin at all — making a show, making an episode. |
complete |
A test answering has this been done? from the data itself. |
requires |
Field keys that must have a value before it can start. |
produces |
Field keys it leaves behind. |
automatic |
Whether it starts itself as soon as its requirements are met. |
Completion is derived, never stored as a flag. A flag can lie: a file is deleted, an edit is undone, a show is copied from another machine. Asking the data is slower and always true. A user may still mark a step done by hand, for the activities that leave no trace.
States¶
Every step is judged on its own, in this order. The order is the whole definition.
| State | When |
|---|---|
needs_plugin |
Nothing installed, and not the shell, can serve it. |
done |
The data says so, or the user did. |
ongoing |
A task is running for it right now. |
active |
Its page is open in front of the user, and it is not finished. |
not_ready |
Something it requires does not exist yet. |
ready |
It can be started. |
A needs_plugin step is drawn, not hidden, wherever the workflow is drawn as a map — the
strip across the top and the workflow page. A map with its unreachable parts rubbed out stops
being one. The row is drawn faded and grey, its tooltip names the plugin it is waiting for —
switched off, or not installed at all — and clicking it opens a box that says why, with two
buttons: Close, and Plugins. It used to go straight to the Plugins screen, which is an
application answering a click with a page nobody asked for; now the user is told what is in the
way and chooses. Grey rather than the warning colour: it is not a fault, it is work this
build cannot do.
The home page's cards leave those steps out. A card is not a map, it is a glance at how far
one podcast has got, and a row of marks for work that cannot be done at all answers a question
nobody asked of it. read_steps is where that happens, so the two readings come from one
traversal.
It is not counted by completion: a step nobody can serve is not work outstanding, and counting
it means a progress bar that can never reach its own end.
There is still no where was I step. Work on a podcast is not a queue: several steps are commonly under way at once, and several can be waiting on different things. Singling out one place as the place you are hides that, and was wrong as often as it was right.
active is not that. It says "this one is open in front of you and unfinished", which is a fact
about the window rather than about the show, and it is the one state the traversal does not work
out: the shell passes in the step whose page is open and everything else is read from the show
file. A step that runs itself is never marked active — nobody is filling it in, and the mark
would stop it starting, since ready is what sets an automatic step going.
ongoing is read from the task registry rather than stored, so a crash cannot leave a step
claiming to be running. not_ready is computed from requires, and the interface says which
field is missing — "not ready" with no reason is a slower way of saying no.
Steps that start themselves¶
An activity declared automatic runs as soon as everything it requires exists, nothing is
running for it, and it is not already done. This is how a hand-made step chains into a machine one:
the user marks the audio imported, the workflow is drawn again, and transcription begins without
being asked.
Nothing is remembered about having started one. It will not be offered again while its task runs, nor once its work is there — and both of those are read from the data, so a crash loses nothing and repeats nothing. The engine only says which steps are waiting to start; it starts nothing itself, because it has no idea what a process is.
Workflows¶
A workflow is an ordered list of activity ids with a name. There are three sources, offered to the user in this order:
| Source | Where it lives |
|---|---|
| Shipped | full and quick for an episode, one for a podcast, one for the application |
| Offered by a plugin | declared through podlibre_workflows; arrives with the plugin and leaves with it |
| The show's own | saved in the show file when the user edits one |
The shipped ones stay first because the first in the list is what a show with no choice recorded falls back to — so what a plugin offers cannot become anybody's default by arriving.
Workflows belong to the show, not to the application. A show chooses which it uses, and may hold
workflows of its own; both live in workflow_state in the show file, so copying the folder to
another machine takes the way of working with it. Editing one is adding and removing steps — and
since a plugin appears as the steps it declares, that is the same thing as adding and removing
plugins. A shipped workflow is never overwritten: saving under its id makes a copy of your own that
takes precedence, so the originals are always there to go back to. Neither a shipped workflow nor
one a plugin offers is the user's to delete; saving makes a copy of their own either way.
A workflow keeps an id nothing defines any more rather than dropping it, so uninstalling a plugin and putting it back brings its step back where it was. A show using a workflow that has gone — because the plugin offering it was switched off — falls back to a shipped one rather than being left with no way of working, and gets it back when the plugin returns.
A podcast has one too¶
Making a podcast is not only making its episodes, so the show scope carries a workflow of its own: describe it, work through its episodes, publish it. The same engine draws it from the same kind of rows, and its completion is derived the same way — the podcast is described when it has a description, its episodes step is done when it has episodes, and it is published when the feed is where it says it will be.
Publishing is a step of the podcast rather than of an episode because one feed covers every episode, and where the files go is a field on the show. Laying the episodes out as files is part of publishing rather than a step before it. It was a step of its own, and it was the same step: the files it wrote were read by nothing but publishing, publishing refused to run until it had them, and a user who had done only the first had a folder of audio and a podcast that was still not published. Podlibre ships the step and serves it with nothing: the bundled folder publisher provides it, and a plugin for a host would provide the same one. An episode's own work therefore ends with its metadata.
A step may be refused. Plugin.start asks the window before it runs
anything, and the window asks whoever opened the show. The one rule today is
about publishing: a podcast missing a field a directory demands — a
description, a language, artwork, a category — does not publish, and the user
gets the list of what is empty instead, with each row a way to the field. It
lives there rather than in the folder publisher so that every plugin that
publishes is held to it, including the ones nobody has written yet, and so
that no step on the way to publishing is blocked by it: a workflow that would
not let you edit audio until the feed was valid has the dependency backwards.
Its three steps are three phases, and that is deliberate rather than an accident of grouping: describing a podcast, working through its episodes and publishing it are three kinds of work, and a phase is what the workflow page puts a heading on. Opening a podcast or an episode opens the first step of its workflow, not the list of them: the list is a map, and a map is what you consult, not where you stand.
Plugins contribute¶
A plugin declares activities through a hook. An activity whose id matches one Podlibre ships
replaces it, which is how a third party takes over a step — serving transcribe with a
different engine, say — rather than adding a competing entry beside it.
A plugin may also offer a whole workflow, which is what a plugin covering a way of working
end to end needs: without it, a plugin could serve every step of a sequence and still leave the
user to assemble the sequence and guess the order. It is offered, never imposed — it joins the
list and the user chooses. Its id is prefixed with the plugin's own, so two plugins may each offer
a simple.
When two plugins serve one step¶
Podlibre is organised around the workflow, so a step has to be swappable between plugins that do the same job: installing a second transcription plugin must not break the first, and choosing between them must not mean uninstalling one.
Who serves a contested step is decided once, by the registry, and read back from the activity it chose — so the page a step opens and the state the step is drawn in cannot disagree. They were once worked out separately, over two different orderings, and with two plugins installed they named different plugins: the step opened one plugin's page while the workflow believed the other served it, decided that one was not installed, and left a working page with no step to open it.
The rule is the plugin switched on most recently serves the step, and the choice is recorded in the settings file, keyed by step. It has to be recorded: plugins load in discovery order, which is alphabetical, so a rule that lived only in that order handed the step back to whichever plugin sorted last at every launch. Switching a plugin off does not forget that it was chosen — switching off is how you try the other one, switching back on is how you say you meant it. A plugin that was never switched on takes nothing away from one that was, so installing something cannot silently change what serves your workflow; the Plugins screen names the plugin currently serving the step, on every card that offers it.
Which plugin serves a step is kept in the settings rather than in the show file, where the workflow itself lives: which steps a podcast has and in what order is how that podcast is made and travels with it, while which plugin serves a step is a fact about this machine — a show copied elsewhere may not have that plugin at all.
Commands and the Prompt¶
Every action in Podlibre is a command: an id, a title, the scope it makes sense in, and what it does. Menus, keyboard shortcuts and the Prompt in the header are three views of one registry, so a plugin that adds a command gets all three at once, and nothing is reachable by one route and not another.
The Prompt searches commands first, then episodes by title across every show, ranked with
recency. What matches neither can be asked instead: the last row of the list offers it to
podlibre_answer, which runs as a task on a worker thread. Podlibre ships nothing that answers,
so until a plugin implements that hook the row says what would make it work.