Plugin reference¶
A plugin is a folder of Python. Two rules are the whole of how Podlibre finds one:
| The folder name | your plugin's id |
A class whose name ends in Plugin |
the plugin |
The folder is imported as a Python package, so its name must be one Python can import: lowercase
letters, digits and underscores, not starting with a digit. my-plugin is refused, by name, with
the reason. You do not need an __init__.py.
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 plugin folder in the user's
plugin directory replaces a bundled one of the same name.
There is no manifest. Everything you contribute, you declare in code.
The whole of a plugin¶
from podlibre.plugin import Plugin, Step, Field, Flow
class TranscribePlugin(Plugin):
"""Turns an episode's audio into a transcript."""
name = "Transcribe"
uses = ["models"]
steps = [Step("transcribe", phase="transcribe",
requires=["audio_file"], produces=["transcript"],
automatic=True)]
fields = [Field("transcript", on="episode", type="url")]
def build(self):
return my_widget # or nothing at all
def run(self, step):
with self.working(self.t("working"), total=len(chunks)) as w:
for n, chunk in enumerate(chunks, 1):
if w.stopped:
break
...
w.step(n)
Three rules remove most of the decisions:
build()is the only method called on the thread that draws. Return a widget and Podlibre makes it a page of its own, reachable from your step and from the Prompt.run()is always called on a worker thread. You never write threading code, and you cannot freeze the window by accident. Do not touch a widget from it — usesay(), or do it in a method the UI calls.- You never name yourself. Your id is your folder name; Podlibre fills it into everything you declare.
A plugin with no page at all is a complete plugin — opening its step runs it. That is what an
uploader or a converter wants to be: a Step, a run(), and nothing else.
What you declare¶
steps¶
A list of Step. Each is a step in the workflow, which is where people look for work to do.
Step("transcribe",
scope="episode", # "application" | "show" | "episode"
phase="transcribe", # start show episodes prepare transcribe
# edit enrich export publish
requires=["audio_file"], # fields you need before you can start
produces=["transcript"], # fields you leave behind
automatic=True, # start by yourself once `requires` is met
icon="text", # optional glyph
complete=lambda ctx: ...) # how to tell it is already done
An id matching one Podlibre ships replaces that step rather than appearing beside it. That is
how you take over transcription with your own engine. A replacement that names no icon keeps
the one the shipped step has, and a step of your own that names none is drawn with a generic
mark: every step on screen carries one, so you never have to go looking for the name of a glyph
to be drawn like everything around you.
requires is what turns ready into waiting, and it lets Podlibre tell the user which
field is missing rather than only that something is. An automatic step with no requires would
start the instant the workflow was drawn, for ever.
complete is (Context) -> bool, for a step that can tell whether it is done by looking. Leave it
out and the step is done when the user ticks it. Deriving it is better wherever you can: a tick is
a second record of something the show already knows, and the two drift apart — a file deleted
outside Podlibre leaves a step still ticked. A step that produces fields is already derived from
those, so complete is for a step whose evidence is something else.
Your step's name and hint come from your own catalogue, as activity.<id>.title and
activity.<id>.hint.
fields¶
A list of Field. Yours sit beside the iTunes and Podcasting 2.0 fields and are read and written
through the same calls — see the data model.
Field("mood",
on="episode", # "show" | "episode"
type="choice", # one of the twelve
choices=("calm", "tense"),
rss="podcast:person", # where it goes on the way out, if anywhere
id3=None,
shared=True) # may other plugins read it
shared=True is how a field becomes useful beyond you: an exporter can put it in the feed
without ever having heard of your plugin. You may not redefine a field another layer already
owns — use your own key.
workflows¶
A list of Flow, for when you serve several steps and know the order they go in. Podlibre is
organised around the workflow, so this is how a plugin says how its steps fit into the work
rather than leaving the user to assemble them.
Flow("simple", "Simple", # your id, and the name shown in the editor
scope="episode", # "application" | "show" | "episode"
steps=["import_audio", # ids in the order they should be done —
"transcribe", # yours and Podlibre's alike
"metadata"])
It is offered, not imposed: it joins the shipped workflows and the user's own in the workflow
editor, and the user chooses. Its id is prefixed with your folder name, so offering a simple
cannot collide with a shipped workflow or with somebody else's.
Name any step id, whether or not anything serves it yet. One nothing serves is kept in the workflow and drawn faded: it cannot be opened, started or finished, and it says so — clicking it offers the Plugins screen rather than doing nothing. Installing the plugin that serves it, or switching that plugin on, wakes the step where it was named. What is installed and what is not is the Plugins screen's business to say.
uses¶
What your plugin does, from a fixed vocabulary: network, files, audio, models,
processes. Fixed rather than free-form, so two plugins describing the same thing use the same
word; anything outside it is dropped.
This is a claim, not a permission. Podlibre does not enforce it and cannot: your plugin shares this process and can do anything the person running Podlibre can do. The Plugins screen says so, in full, above the list.
Who you are¶
class TranscribePlugin(Plugin):
name = "Transcribe" # what Podlibre calls you on screen
identifier = "org.example.transcribe" # reverse-DNS, and yours alone
author = "Your name"
version = "1.0.0" # major.minor.patch
date = "2026-10-05" # when this version was made
homepage = "https://example.org/t" # optional; a link on your card
Without name, your folder name is made readable, which gives "Rss import".
identifier is the name that cannot collide. Your folder name is only how Podlibre imports you,
and two people may both reasonably call a folder transcribe; reverse-DNS from a domain you
control does not have that problem.
A plugin missing any of these still loads — somebody halfway through writing one should not be stopped by a missing date. The Plugins screen lists what is missing, on the card where a user decides whether to trust you.
What you are given¶
self.show |
the open show, or None — check it |
self.episode_id |
the open episode, kept current for you |
self.t(key, **kw) |
your own strings, from your locales/ |
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 in the Tasks tab, with progress and Stop |
self.start(step) |
run a step yourself, on a thread |
self.settings |
your own settings, kept between runs — or None |
self.id, self.directory |
your folder name, and where your files are |
self.settings is get(key, default) and set(key, value), in a section of Podlibre's settings
file keyed by your plugin's id — so a chosen model or a server address survives a restart and no
other plugin can read it by accident. Not for secrets. It is a readable file in the user's
state directory; an API key belongs in their environment.
working() is the one to read twice:
with self.working("Tagging", total=len(episodes)) as w:
for n, episode in enumerate(episodes, 1):
if w.stopped: # the user pressed Stop
break
...
w.step(n, episode.title)
It registers the task, reports progress, and finishes it even if the body raises — a task
left running for ever is worse than the error. 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.
What Podlibre tells you¶
Override the ones you care about. You never match on an event name.
episode_opened(episode_id, values) |
an episode was opened; self.episode_id is already set |
episode_closed() |
it was closed |
show_changed() |
something worth redrawing was written — by another plugin, or by your own step finishing |
retranslate() |
the language changed; self.t already answers in the new one |
Underneath, this is one hook — on_event(event_name, event_data) — that every plugin receives.
A plugin that wants it raw can implement it directly; the base class is a convenience, not a
second architecture. The events are current_info, episode_closed, show_changed,
language_changed and start_activity.
Underneath: the hooks¶
The base class is a convenience, not a second architecture. It implements five
pluggy hooks from the attributes above, and a plugin that wants
them raw can implement them itself with @hookimpl from podlibre.loader and inherit nothing:
| Hook | Returns |
|---|---|
podlibre_activities() |
a list of workflow.Activity — what steps becomes |
podlibre_fields() |
a list of fields.FieldDef — what fields becomes |
podlibre_workflows() |
a list of workflow.Workflow — what workflows becomes |
podlibre_uses() |
a list of words — what uses becomes |
podlibre_answer(question) |
an answer, or None — see below |
on_event(event_name, event_data) |
the data, so the next plugin sees your change |
Doing that means filling in provides and owner yourself, and matching event names by hand.
There is no advantage unless you are doing something the base class does not allow.
Answering a question¶
podlibre_answer(question) is the one hook with no attribute behind it, because it is not
something you declare — it is something you do. The field in the header is a command line and a
question box at once: what is typed is matched against the commands and the open show's episodes,
and the row at the bottom of the list offers to ask it instead.
from podlibre.loader import hookimpl
class OraclePlugin:
@hookimpl
def podlibre_answer(self, question):
if not question.endswith("?"):
return None # not mine
return my_model.answer(question)
The first answer wins: the user asked once, so this is the only hook that stops at the first
plugin to return something. Return None to say "not mine", which is what every plugin that is
not an assistant does by not implementing it at all.
It is called on a worker thread, as a task with its own row in Tasks, because a model on this machine takes seconds and the window must not stop. Answer with text; the shell puts it under the field. Podlibre ships nothing that answers — the models arrive with the milestone that funds them — so until a plugin implements this, the Prompt says what would make it work rather than pretending to offer it.
Translating yourself¶
Your strings live in locales/<code>.po beside your code, read through self.t(). Podlibre's
own catalogue holds no keys for an extension it has never heard of. The language travels with the
language_changed event, and your catalogue is reloaded before retranslate() is called.
Podlibre reads .po directly — there is no build step.
What you may import¶
Podlibre's own dependencies — everything in its requirements.txt — and the standard library.
You cannot bring a dependency of your own: there is no per-plugin environment and no install
step, so a plugin needing something new is a change to Podlibre's requirements and a conversation.
When it does not load¶
A plugin that fails to 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, and run Podlibre from a terminal while you are working on one.
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. The choice is remembered in
settings.json beside your library, alongside anything the plugin itself keeps.
If two plugins declare the same step — which is supported, and is how one replaces another — the one switched on most recently serves it, and that choice is remembered too, so it is still yours after a restart. Both keep their pages, and each of their cards names the plugin currently serving the step. See the workflow engine.