What a plugin can and cannot do¶
Every feature in Podlibre is a plugin, including the ones it ships with. This page is the boundary: what the application hands you, what you may call, and what is deliberately not possible.
For how to write one, see Writing a plugin. For the exact signatures, see the Plugin reference. This page is about the limits.
In one sentence¶
A plugin is a folder of Python that Podlibre imports into the same process it runs in, registers with pluggy, and gives a page, a place in the workflow, and a handful of its own objects to work with.
There is no separate process, no sandbox and no isolation of any kind. Everything below follows from that.
What you can do¶
| Add steps to the workflow | steps = [Step(…)] — yours sit beside the shipped ones |
| Offer a whole workflow | workflows = [Flow(…)] — steps in an order, under a name, for the user to choose |
| Replace a step, or a whole shipped plugin | see Replacing something Podlibre already does |
| Add fields to a show or episode | fields = [Field(…)] — stored, exported and edited exactly like the iTunes ones |
| Add a page | return a widget from build(); it is mounted and reachable from your step and the Prompt |
| Do slow work | run(step) is always called on a worker thread, with a task and a Stop button |
| Read and write the open show | self.show, the full Show API below |
| Keep your own settings | self.settings — get/set, in your own section of the settings file |
| Speak the user's language | self.t(key), from your own locales/*.po |
| Hear what happens | override episode_opened, episode_closed, show_changed, retranslate |
| Answer what is typed into the Prompt | implement podlibre_answer(question) — the first answer wins |
| Read another plugin's fields | if that plugin declared them shared=True |
A plugin with no page at all is a complete plugin: a Step, a run(), and
nothing else. That is what an uploader or a converter wants to be.
What you cannot do¶
You cannot bring your own dependencies¶
There is no per-plugin environment and no install step. You may import Podlibre's own dependencies and the standard library, and nothing else:
A plugin that needs something new is a change to Podlibre's requirements.txt
and a conversation. This is the single hardest limit on the list, and it is
deliberate: a plugin directory is a folder you copy, not a package you install.
You cannot touch a widget from run()¶
run() is on a worker thread. Qt widgets may only be touched on the thread
that drew them. Use self.say(message) for the status line — that one is safe
from any thread — or do the UI part in a method the interface calls.
build() is the only method called on the drawing thread.
You are not sandboxed, and uses is not a permission¶
uses = ["network"] is a claim, from a fixed vocabulary. Podlibre does not
enforce it and cannot: your code runs in the same process as everything else
and can do anything the person running Podlibre can do. The Plugins screen says
so, in full, above the list.
The vocabulary is network, files, audio, models, processes. Anything
outside it is dropped rather than shown, so one plugin cannot invent a
reassuring phrase of its own.
You cannot redefine another layer's field¶
register_fields refuses to shadow a field another owner already defines. Use
your own key. One extension silently changing another's data is worse than a
failed install.
You cannot name yourself¶
Your id is your folder name, and Podlibre fills it into everything you declare
— provides on your steps, owner on your fields. There is no attribute for
it. A stringly-typed back-reference that can be silently wrong is a bug waiting
to happen.
You cannot store a secret¶
self.settings is a readable JSON file in the user's state directory. An API
key belongs in their environment, not there.
Other things that are simply not built¶
- No way to install a plugin from inside the application — drop a folder in the
plugin directory, or run with
--plugin-dir PATH. - No plugin ordering or priority. Event order is pluggy's own.
- No way for one plugin to call another directly. They meet through fields and the event bus, which is what lets any of them be removed.
- No scheduler, and no way to be woken up when Podlibre is not running.
- Nothing stops you starting your own thread, but work started outside
run()is work the Tasks tab cannot show and the user cannot stop. Useself.start(step)and it is a task by construction.
What you are given¶
On self, from the base class:
self.show |
the open Show, or None — check it |
self.episode_id |
the open episode's id, kept current for you, or None |
self.settings |
your own settings (get(key, default), set(key, value)), or None |
self.t(key, **kw) |
your own strings |
self.say(message) |
the status line; safe from a worker thread |
self.mark(button, name) |
one of Podlibre's icons on a button of yours |
self.working(title, total) |
a task with progress and a Stop button |
self.listen() |
play the open episode in Podlibre's player, in the drawer |
self.start(step) |
run one of your steps yourself, on a thread |
self.id |
your folder name |
self.directory |
where your files are |
self.window |
the shell — not a supported surface; see below |
self.window is how the base class does its work, and it is a real
MainWindow. Nothing stops you using it, and nothing promises it will look the
same next version. Everything on the table above is the supported way.
mark() is worth using on every button you draw. Every button the shell draws
carries an icon, so a page of bare words looks like a page from another
application. The names are the ones a step names its icon with — wave,
upload, rss, folder, play, stop, plus — and they are drawn from the
desktop's theme, from the bundled PodcastFont, or painted, whichever that
machine has. The colour is not yours to choose: it follows the theme, and the
theme can change while your page is on screen.
working() — the one to read twice¶
with self.working(self.t("working"), total=len(items)) as w:
for n, item in enumerate(items, 1):
if w.stopped: # the user pressed Stop
break
...
w.step(n, item.name)
It finishes its task even if the body raises, and w.stopped is the only
way the Stop button reaches your loop. A long loop that never reads it is a
task the user cannot interrupt.
Podlibre starts a task for every run() whether or not you open a block, so
your work is always visible and always stoppable; working() names it and
gives it progress.
Give it a total, and choose the unit carefully. The percentage on the
status bar and under your page is done / total; without a total the bar
sweeps and says no number, which is the truth for work nobody has measured
but not much use to whoever is waiting. Count something that advances
smoothly: the folder publisher counts milliseconds of audio rather than
episodes, because counting episodes meant a podcast with one episode sat at
0% for half a minute and then jumped to 100%. If your run() does two
different kinds of work, open a block for each — a second working() names
the task again and starts the count from nought.
Podlibre draws the tasks you started in the Tasks tab, in the drawer at the foot of the window, with their progress and their Stop. You do not have to draw any of that, and you should not draw it again on your own page: the same work in two places is two numbers to keep in step.
Podlibre may refuse a step¶
self.start(step) can come back having done nothing: a step may be refused
while the podcast is not ready for it — a publishing step is, while a field
a directory demands is empty — and whoever refused tells the user why and
what to fill in. Do not work around it by calling run() yourself; a step
that publishes a feed no directory will accept has not helped anybody.
The core API¶
Everything here is importable and stable. Anything not listed is internal.
The show — self.show¶
Episodes
add_episode(title, *, slug=None) |
→ Episode |
episode(episode_id) |
→ Episode, raises if absent |
episodes() |
→ list[Episode] |
find_episodes(query, limit=6) |
→ list[Episode] |
remove_episode(episode_id) |
Fields — target is F.SHOW or F.EPISODE
field(target, target_id, key) |
one value, typed |
set_field(target, target_id, key, value) |
|
all_fields(target, target_id) |
→ dict |
set_fields(target, target_id, values) |
several at once |
show_field(key) / set_show_field(key, value) |
the show's own, without the ids |
register_fields(defs) |
normally done for you from fields = [...] |
catalogue |
the Catalogue: get, require, for_target, exportable |
Your own fields are registered on a podcast when the shell opens one, and a
page is built before that has happened for a podcast already open: field()
raises for a field that podcast has never heard of. Ask
show.catalogue.get(target, key) first, which answers None instead of
raising.
Audio and files
clips(episode_id) |
→ the episode's clips |
add_clip(episode_id, source, duration_ms, …) |
→ the clip's id. The only way audio becomes part of an episode |
remove_clip(clip_id) |
take one off again. The file is yours to delete or keep |
set_clip_source(clip_id, source) |
point a clip at a new file |
counts(episode_id) |
what the episode holds |
has_export(episode_id) |
|
directory |
the show's folder on disk |
Workflow and marks
workflow(scope=…) / workflows(scope=…) |
the one in use, and all of them |
use_workflow(id, scope=…) |
|
save_workflow(workflow) / delete_workflow(id) |
|
marks(scope, target_id) |
which steps are ticked |
mark(scope, target_id, activity, …) |
tick one |
Bookmarks: bookmarks(), add_bookmark(episode_id, label, …),
remove_bookmark(bookmark_id).
Fields — podlibre.fields¶
SHOW, EPISODE; OWNER_ITUNES, OWNER_PODCAST2; shipped_fields();
FieldDef, Catalogue.
The twelve types: text, longtext, html, url, email, number,
duration, date, bool, choice, list, image. The metadata editor
builds a control for each, so a field you declare is editable with no UI
written for it — except duration, which is drawn as a value and not as a
box: a length is a fact about the audio, and whatever writes the audio writes
it.
Workflow — podlibre.workflow¶
Scopes SCOPE_APP, SCOPE_SHOW, SCOPE_EPISODE. PHASES — start, show,
episodes, prepare, transcribe, edit, enrich, export, publish. States
STATE_NEEDS_PLUGIN, STATE_DONE, STATE_ONGOING, STATE_ACTIVE,
STATE_NOT_READY, STATE_READY, in the order they are decided. Types
Activity, Workflow, Context; readable(id).
You normally meet these through Step and Flow, which fill in the parts
that are Podlibre's business rather than yours.
A Workflow is a name and an ordered list of step ids, and nothing else: which
workflows exist is the user's business, not the engine's. A show keeps the one
it uses in its own file, so copying the show carries the way of working with
it. Offer one with workflows = [Flow("simple", "Simple", steps=[…])] — it
joins the shipped workflows and the user's own in the editor, and the user
chooses. Yours is prefixed with your folder name, so it cannot collide.
Tasks — podlibre.tasks¶
self.working() is the way in. Underneath: TaskRegistry.run(title, work, …)
owns the thread, and start, progress, finish, cancel, running, all,
wait are the rest. States RUNNING, DONE, FAILED, CANCELLED.
Translation — podlibre.i18n¶
t(key, **kw) for Podlibre's own strings, load(directory, language) for a
catalogue, DEFAULT. Use self.t() rather than t(): Podlibre's catalogue
holds no keys for an extension it has never heard of. Podlibre reads .po
directly — there is no build step.
The hooks — podlibre.hookspecs, podlibre.loader¶
EVENTS is the whole event vocabulary: current_info, episode_closed,
show_changed, language_changed, start_activity. USES is the claims
vocabulary. @hookimpl from podlibre.loader is there if you want to
implement podlibre_activities, podlibre_fields, podlibre_workflows,
podlibre_uses or on_event raw and inherit nothing — the base class is a convenience, not a
second architecture. podlibre_answer is only ever written that way: it is the
one hook with no attribute behind it, because answering is something a plugin
does rather than something it declares.
What this means for the obvious plugins¶
Four things people reach for first. Each is possible today; the differences are in what Podlibre already does for you and what you do yourself.
| Possible today | What you call | |
|---|---|---|
| Download from the network | yes | requests |
| Upload to a hosting platform | yes | requests |
| Transcription | yes | faster_whisper, in the dependency list |
| A language model | yes, but you call it yourself | requests to Ollama, or a provider's HTTP API |
On the last one, read Language models and then
read this: that page describes a planned capability system that does not
exist yet. There is no self.model, no capability request, no cost
accounting, no installer. Today a plugin that wants a model opens a socket like
any other plugin. When the system lands, this page will say so.
Transcription is the same shape: faster-whisper is in requirements.txt so
you may import it, but nothing in Podlibre wraps it. The transcription step is
in the shipped workflow, drawn faded, until somebody writes one.
Worked example: publishing to a Castopod instance¶
The example worth having, because it exercises nearly everything: settings,
credentials, requires/produces, a long upload with a Stop button, two
chained HTTP calls, and writing the result back as fields another plugin can
read.
Castopod's REST API is off by default — the instance owner enables it in
.env with restapi.enabled, restapi.basicAuth and a username and password.
Adding an episode is POST /episodes, multipart/form-data, requiring
user_id, updated_by, title, slug, podcast_id and a binary
audio_file; publishing it is POST /episodes/{id}/publish with a
publication_method of now, schedule or with_podcast. The base path is
not given in the documentation — installs report api/rest/v1/, so make it a
setting rather than a constant.
import os
import requests
from podlibre import fields as F
from podlibre.plugin import Field, Plugin, Step
class CastopodPlugin(Plugin):
"""Publishes a finished episode to a Castopod instance."""
name = "Castopod"
identifier = "org.podlibre.castopod"
author = "Your name"
version = "1.0.0"
date = "2026-10-11"
homepage = "https://castopod.org"
uses = ["network", "files"]
# `requires` is what turns *ready* into *waiting*: without audio there is
# nothing to upload, and Podlibre says which field is missing rather than
# letting the user press a button that cannot work.
# Its own id, not the shipped `publish_host`: that one is the podcast
# handed to a host whole, and this uploads one episode. A step a plugin
# invents is in the workflow like any other.
steps = [Step("castopod_upload", phase="export",
requires=["audio_file", "title"],
produces=["castopod_url"],
complete=lambda c: bool(c.episode_field("castopod_url")))]
# Declared, so they are stored, editable and exportable like any other
# field -- and `shared=True` lets an exporter put the address in the feed
# without ever having heard of this plugin.
fields = [Field("castopod_id", on="episode", type="number"),
Field("castopod_url", on="episode", type="url", shared=True)]
def run(self, step):
show, episode_id = self.show, self.episode_id
if show is None or episode_id is None:
return
site = (self.settings.get("site") or "").rstrip("/")
path = self.settings.get("api_path", "api/rest/v1")
podcast_id = self.settings.get("podcast_id")
user_id = self.settings.get("user_id")
# NOT in settings: that file is readable and is not for secrets.
password = os.environ.get("CASTOPOD_PASSWORD", "")
if not (site and podcast_id and user_id and password):
self.say(self.t("castopod.not_configured"))
return
values = show.all_fields(F.EPISODE, episode_id)
audio = values.get("audio_file")
if not audio or not os.path.isfile(audio):
self.say(self.t("castopod.no_audio"))
return
episode = show.episode(episode_id)
form = {
"user_id": user_id,
"updated_by": user_id,
"podcast_id": podcast_id,
"title": values.get("title") or episode.title,
"slug": episode.slug,
"description": values.get("description") or "",
"parental_advisory": "explicit" if values.get("explicit") else "clean",
}
# Only what the episode actually has: Castopod rejects an empty
# integer, and sending "" for a season nobody set is a 400 that reads
# like a bug in Podlibre.
for ours, theirs in (("episode_number", "episode_number"),
("season", "season_number"),
("episode_type", "type")):
if values.get(ours):
form[theirs] = values[ours]
with self.working(self.t("castopod.uploading"), total=2) as work:
with open(audio, "rb") as handle:
made = requests.post(
f"{site}/{path}/episodes",
auth=(self.settings.get("username", ""), password),
data=form,
files={"audio_file": (os.path.basename(audio), handle)},
timeout=600)
# Not swallowed: the task is marked failed, the reason reaches the
# status line, and it is in the Tasks tab afterwards.
made.raise_for_status()
created = made.json()
work.step(1, created["slug"])
if work.stopped: # uploaded but not published; still useful
show.set_field(F.EPISODE, episode_id, "castopod_id", created["id"])
return
published = requests.post(
f"{site}/{path}/episodes/{created['id']}/publish",
auth=(self.settings.get("username", ""), password),
data={"publication_method": "now"},
timeout=60)
published.raise_for_status()
work.step(2)
show.set_fields(F.EPISODE, episode_id, {
"castopod_id": created["id"],
"castopod_url": published.json().get("audio_url", "")})
What Podlibre did for you here: put the step in the workflow, refused to offer it until there was audio, ran it off the drawing thread, gave it a progress bar and a Stop button, finished the task when it raised, and made the two new fields editable and exportable. What you wrote: the HTTP.
The same shape, for any host¶
Nothing above is Castopod-specific except the field names and the two paths.
An uploader for another platform differs in its form keys and its auth. If the
host uses a token rather than Basic auth, it is still
os.environ for the secret and self.settings for everything else.
Worked example: transcription¶
import os
from faster_whisper import WhisperModel
from podlibre import fields as F
from podlibre.plugin import Field, Plugin, Step
class WhisperPlugin(Plugin):
"""Turns an episode's audio into a transcript, on this machine."""
name = "Whisper"
uses = ["models", "files"]
# `automatic` starts it the moment its requirement is met -- the import
# finishes and transcription begins without being asked.
steps = [Step("transcribe", phase="transcribe",
requires=["audio_file"], produces=["transcript"],
automatic=True,
complete=lambda c: bool(c.episode_field("transcript")))]
fields = [Field("transcript", on="episode", type="url", shared=True)]
def run(self, step):
show, episode_id = self.show, self.episode_id
audio = show.field(F.EPISODE, episode_id, "audio_file")
model = WhisperModel(self.settings.get("model", "small"),
device="auto", compute_type="int8")
segments, about = model.transcribe(audio)
written = os.path.join(show.directory, "episodes", f"{episode_id}.vtt")
with self.working(self.t("whisper.working"),
total=int(about.duration)) as work:
with open(written, "w", encoding="utf-8") as handle:
handle.write("WEBVTT\n\n")
for segment in segments:
# An hour of audio is minutes of work: a loop this long
# that never reads `stopped` is one the user cannot escape.
if work.stopped:
return
handle.write(f"{segment.start:.3f} --> {segment.end:.3f}\n"
f"{segment.text.strip()}\n\n")
work.step(int(segment.end), segment.text[:40])
show.set_field(F.EPISODE, episode_id, "transcript", written)
produces=["transcript"] is what makes the next step possible: anything
declaring requires=["transcript"] goes from waiting to ready the moment
this finishes, with no plugin knowing the other exists.
Worked example: asking a language model¶
There is no model API yet, so you make the call. Ollama on the user's own machine is the path Podlibre intends to support first:
def run(self, step):
transcript = self.show.field(F.EPISODE, self.episode_id, "transcript")
with open(transcript, encoding="utf-8") as handle:
text = handle.read()
with self.working(self.t("notes.writing")):
answer = requests.post(
f"{self.settings.get('ollama', 'http://localhost:11434')}"
"/api/generate",
json={"model": self.settings.get("model", "llama3.1:8b"),
"prompt": f"Write show notes for this episode.\n\n{text}",
"stream": False},
timeout=300)
answer.raise_for_status()
self.show.set_field(F.EPISODE, self.episode_id, "description",
answer.json()["response"].strip())
Two things to be honest about. Nothing meters this — the budget ceilings and per-plugin costs in Language models are not built, so a plugin calling a paid provider spends the user's money with no warning; say so in your description. And check Ollama's own documentation for the request shape, which is theirs to change, not Podlibre's.
Worked example: downloading¶
fetch_all in plugins/rss_import/rss_import_plugin.py is this: the audio,
the covers, the transcripts and the chapter lists a feed points at, fetched one
at a time. publish_show in plugins/local_publish/local_publish_plugin.py is
the same loop over local files. The pattern that matters:
# One session for the lot: `requests.get` opens a connection and closes it
# again per call, so a back catalogue pays for a TLS handshake per file.
with self.working(self.t("import.downloading"),
total=len(episodes)) as work, requests.Session() as net:
for number, episode in enumerate(episodes, 1):
if work.stopped:
break
name = f"{episode['slug']}.mp3"
destination = os.path.join(show.directory, "episodes", name)
os.makedirs(os.path.dirname(destination), exist_ok=True)
try:
response = net.get(episode["audio_url"], timeout=120,
stream=True)
response.raise_for_status()
with open(destination, "wb") as handle:
# Streamed, not `response.content`: an episode is a hundred
# megabytes and the user is watching a progress bar.
for chunk in response.iter_content(chunk_size=65536):
handle.write(chunk)
except Exception as exc: # noqa: BLE001
# One dead enclosure is ordinary: feeds outlive their hosting.
# The episode is imported without its audio, and the rest proceed.
print(f"{episode['slug']}: {exc}")
continue
work.step(number, name)
Note the one place a bare except is right: a loop over many remote things,
where one failing must not take the other ninety-nine with it. Everywhere else,
let it raise — run() reports it and the task carries the reason.
Always pass a timeout. A request without one hangs for ever on a worker
thread, and the task sits at the same percentage until the user quits.
Replacing something Podlibre already does¶
A plugin does not only add. It can take over a step Podlibre or another plugin already serves, and it can replace a shipped plugin outright. Both are supported paths, not loopholes.
Why this exists¶
The alternative is a fork. Somebody who wants a different transcription engine,
an audio chain built on ffmpeg rather than pedalboard, or a metadata editor
with their newsroom's own required fields should not have to maintain a copy of
Podlibre to get it. Nor should they wait for a release: if the shipped
publisher writes a feed their host chokes on, they can ship a fixed one
themselves on the same afternoon.
It is also what keeps the shipped features honest. Podlibre's own metadata editor is served through the same mechanism a plugin uses, so it enjoys no privilege a third party cannot have.
Taking over a step¶
Declare a Step with the same id. That is the whole of it:
class FancyMetaPlugin(Plugin):
"""A metadata editor with our own house fields."""
name = "Fancy metadata"
steps = [Step("metadata", phase="enrich")]
def build(self):
return my_own_editor
workflow.registry() starts from the built-ins and lets a declared activity of
the same id replace one, so the workflow now holds your definition of the
step — your requires, your produces, your complete test — and the step
opens your page instead of the shipped editor.
This works against shell-served steps too. metadata and show_metadata are
marked shell=True and open Podlibre's own field editors; a plugin declaring
either takes it, and the shell stands aside.
The original is not deleted, only outranked. Switch your plugin off on the Plugins screen and the step goes back to whatever served it before — the shipped editor, or out of the workflow altogether if nothing did. That is the test to run before shipping a replacement: turn it off, and check the user is left somewhere sane.
Two plugins for the same step¶
Podlibre is a workflow, so a step must 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.
The one switched on most recently serves the step, and that is remembered.
Switch the one in use off and the other takes over at once; switch it back on
and it takes the step again. No reinstall, no ordering file, no restart — and
the choice is written to settings.json, so it is still yours at the next
launch. It has to be written down: plugins load in alphabetical order, so a
rule that lived only in that order handed the step back to whichever plugin
sorts last every time Podlibre started.
Switching a plugin off does not forget that it was chosen. Switching it off is how you try the other one; switching it back on is how you say you meant it.
Both remain installed, both keep their pages, and the Plugins screen names the plugin serving the step on both cards — so with two transcription plugins listed, you can see which one is live without switching anything. Say in your description which step you take over, so somebody reading the list can work out why their editor looks different.
Replacing a whole shipped plugin¶
loader.discover() reads the plugin directories in order and later ones
win, with the user's own directory read after the bundled one. A folder named
local_audio in the user's plugin directory replaces the shipped local_audio
entirely — its steps, its fields, its page.
This is the supported way to swap out stock behaviour without patching the application. Keep the id, change the contents.
What you cannot replace¶
Another owner's field. register_fields refuses to shadow a field defined
by a different owner, and the install fails loudly rather than quietly changing
whose data is whose. Take over the step that writes a field if you want it
written differently; do not try to redefine the field itself.
What else this makes possible¶
A menu, not a plan. Nothing in this section is scheduled, promised or required, and none of it is needed for Podlibre to be finished — the roadmap says what is. It is here because the quickest way to understand what a plugin surface allows is to see what could be built on it.
A way of working, in one plugin¶
A plugin can offer a workflow as well as steps, so one folder can carry a
whole way of working: the steps it needs, and the Flow that puts them in order
under a name. Interview show, solo recording published the same day, audio
drama — each a plugin somebody switches on, which then appears in the workflow
editor beside the shipped ones for the user to choose.
Nothing stops such a plugin serving every step itself, and nothing requires it to: a workflow is a list of ids, so it can name steps other plugins serve and simply arrange them. The ones nobody serves are drawn faded until something does, and a workflow where that is true of every step is not offered at all.
The steps the shipped workflow leaves open¶
The episode workflow names eight steps. Three are served today: the audio importer, the four filters as one step, and the metadata editor, which is the shell's own. The other five are drawn faded, each saying which plugin it is waiting for:
transcribe · correct_transcript · edit_audio · insert_music ·
chapters
The podcast's own workflow has three, all served: its metadata and its
episodes by the shell, and publish_show by the bundled folder publisher,
which is a plugin's slot like any other. publish_host is shipped beside it,
outside the default, for a plugin that hands the whole podcast to a host.
The application's own workflow has three, all served: create_show and
add_show by the shell — making a podcast, and opening one that is already
on this machine — and import_show by the bundled feed importer, which is a
plugin's slot like any other and the one place a plugin is asked to work with
no podcast open at all.
Each is a plugin's slot, already named, already in the right phase, already
translated. Declaring Step("chapters", …) puts you in it.
Worth reading as a lesson in how requires/produces chain: the four audio
filters all require audio_file, and for a long time nothing produced it,
so they stayed at waiting — finished, tested, and unreachable. One plugin
that writes that one field turned all four on. That is the mechanism working
as designed, and it is why produces is worth declaring even when nothing
consumes it yet.
Podcasting 2.0¶
The case the field system was built for: a plugin declares a field, and an exporter puts it in the feed without having heard of the plugin.
| Chapters | a waveform with markers → podcast:chapters |
| Transcript correction | transcript beside audio; click a line to hear it |
| Soundbites | select a passage → podcast:soundbite |
| Persons | podcast:person with roles, and a reusable address book per show |
| Value splits | podcast:value recipients |
| Podroll, remote items | cross-promotion between shows |
With a language model¶
Once a plugin has a model to call, by whatever means:
- show notes and summaries from the transcript
- proposed chapter marks, which a human accepts or rejects faster than placing
- finding quotable passages and turning them into soundbites
- alternative titles and descriptions to choose between
- translating a transcript, which with per-language
podcast:transcriptis a real accessibility gain
Reaching other services¶
Uploading to a host, mirroring an episode as a podcast:alternateEnclosure,
announcing a release on a social network, pinging an index, or generating a
static feed and page for somebody self-hosting from a bucket. All of them are
the Castopod example above with different form keys.
Things that are simply useful¶
A loudness report explaining why an episode misses −16 LUFS, given Podlibre already measures it. A silence and filler trimmer with a preview of what it would cut. A feed validator that says which directories would reject this show and why.
How Podlibre finds you¶
Two rules, and no manifest:
- The folder name is your id. It must be importable by Python: lowercase
letters, digits and underscores, not starting with a digit.
my-pluginis refused, by name, with the reason. You do not need an__init__.py. - A class whose name ends in
Pluginis the plugin.
Every .py file not starting with __ is imported, each inside its own try.
A file that fails is reported and skipped, and the rest of your plugin still
loads. A folder in the user's plugin directory replaces a bundled one of the
same name.
Say who you are, or the Plugins screen will say you did not:
name = "Transcribe"
identifier = "org.example.transcribe" # reverse-DNS, and yours alone
author = "Your name"
version = "1.0.0"
date = "2026-10-11"
homepage = "https://example.org/transcribe" # optional
Missing ones are reported on the card, never refused — somebody halfway through writing a plugin should still be able to run it.
When it goes wrong¶
A plugin that will not import is reported and skipped so that Podlibre still starts, which means it fails quietly. It is listed on the Plugins screen with the file and the reason. While you are working on one, run Podlibre from a terminal.
Each plugin has a switch on that screen. Switching one off unregisters it and
takes its page away at once; its steps leave the workflow with it. A plugin
that is off is still described, so you can see what you would get back.
The choice is remembered in settings.json beside your library.