Writing a plugin¶
From nothing to a plugin that adds a step to the workflow, saves a field and does something slow without freezing the window.
Before you start¶
You need Podlibre and about twenty minutes. You will write PySide6 widgets — a little Qt, not much — because a plugin builds its own page. Your plugin runs on Podlibre's own interpreter, so a ready-made build is enough; running Podlibre from source, which is the easier way to watch a plugin fail, needs Python 3.14 or newer.
Two rules are the whole of how Podlibre finds you:
- The folder name is your plugin's id. It is imported as a Python package, so it has to be a
name Python can import: lowercase letters, digits and underscores, not starting with a digit.
my-pluginwill not load, and Podlibre says so by name rather than failing later. You do not need an__init__.py. - A class whose name ends with
Pluginis the plugin. Inherit frompodlibre.plugin.Pluginand the rest of this page is all there is.
There is no manifest. What you contribute, you declare in code.
What you may import¶
Your plugin runs on Podlibre's interpreter, so you may import anything Podlibre depends on —
everything in its requirements.txt — and the whole standard library.
What you cannot do is bring a dependency of your own. There is no per-plugin environment and no install step, and this is deliberate: a plugin that could pull packages in would make any two Podlibre installations different from each other, neither reproducible nor reviewable, and would put the licence of whatever it pulled into a GPLv3 application without anyone deciding to.
If yours genuinely needs something that is not there, that is a change to Podlibre's
requirements.txt and a conversation, not something a plugin settles on its own.
1. Start from the template¶
Press Use this template on
podlibre-plugin-template and you have a
repository with a plugin that already loads. Rename the folder to your id and the class to your
name, and run:
There is no build step.
2. Say who you are¶
from podlibre.plugin import Plugin, Step, Field, Flow
class MoodPlugin(Plugin):
"""How an episode feels, for listeners browsing a back catalogue."""
name = "Mood" # what Podlibre calls you
identifier = "org.example.mood" # reverse-DNS, and yours alone
author = "Your name"
version = "1.0.0" # major.minor.patch
date = "2026-10-11" # when this version was made
homepage = "https://example.org/mood" # optional
That is the whole of the ceremony. You inherit from Plugin, and everything below is either a
class attribute you declare or a method you override.
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 mood. A plugin missing any of these still
loads — somebody halfway through writing one should not be stopped by a missing date — and the
Plugins screen lists what is missing, on the card where a user decides whether to trust you. Your
plugin runs with their permissions, so who wrote it is the most useful thing on that card.
3. Add a step to the workflow¶
The workflow is where people look for work to do, so a plugin that does not appear there is a plugin nobody finds.
An id matching one Podlibre ships replaces that step. That is how you take over transcription with a different engine rather than adding a second entry beside it.
Say what you need, and Podlibre can tell the user why your step is not ready yet:
steps = [Step("tag_mood", phase="enrich",
requires=["transcript"], # waits until there is one
produces=["mood"], # what you leave behind
automatic=True)] # and start by yourself then
You never write who provides the step. Podlibre fills that in from your folder name.
Offering a whole workflow¶
If your steps only make sense in an order, say so rather than leaving the user to assemble them:
It joins the shipped workflows and the user's own in the workflow editor, and the user chooses:
offered, never imposed. Name any step id, yours or Podlibre's; one that nothing serves yet is
kept in the workflow and drawn faded, saying it needs a plugin, until something does. Your id is
prefixed with your folder name, so offering a simple cannot collide with anybody else's.
When somebody else serves your step¶
Two plugins declaring one step is supported — it is how one replaces another. The one switched on most recently serves it, and the choice is remembered between runs. Both plugins stay installed, both keep their pages, and the Plugins screen names the one currently serving the step on both cards. Say in your description which step you take over, so somebody reading the list can work out why their editor looks different.
4. Add a field¶
shared=True lets any other plugin read it — an exporter can put your field in the feed without
ever having heard of you. See the data model.
5. Build your page¶
def build(self):
page = QWidget()
page.setObjectName("EditorPage")
page.setAttribute(Qt.WidgetAttribute.WA_StyledBackground, True)
...
return page
Return a widget and Podlibre mounts it as a page, reachable from your step and from the Prompt.
Reuse Podlibre's objectNames — EditorPage, ScreenTitle, ScreenSubtitle, Card —
and the variant property on buttons, and you look native under every theme including ones
written after your plugin.
Mark your buttons: self.mark(button, "upload"). Every button the shell draws carries an icon,
so a row of bare words reads as a page from somewhere else. The names are the ones the steps use
— wave, upload, rss, folder, file, play, stop, plus — and the colour follows the
theme, which can change while your page is on screen.
Returning nothing is a complete plugin. A plugin with no page runs its step when the step is opened, which is what an uploader or a converter wants to be.
6. Do the work¶
def run(self, step):
with self.working(self.t("tagging"), total=len(episodes)) as w:
for n, episode in enumerate(episodes, 1):
if w.stopped:
break
self.show.set_field(F.EPISODE, episode.id, "mood", mood)
w.step(n, episode.title)
run() is always called on a worker thread, so it may take as long as it takes and you write
no threading code at all. build() is the only method on the thread that draws.
working() registers a task: it appears in the Tasks tab with a Stop button, it is finished
even if the body raises, and w.stopped is the only way that button reaches your loop. A long
loop that never reads it is a task the user cannot interrupt.
Do not touch a widget from run(). Use self.say(...) for a line in the status bar, which is
safe from either thread.
Your own settings¶
self.settings is your own corner of Podlibre's settings file, keyed by your folder name, so no
other plugin can read or overwrite it by accident:
For what the user chose — a model, a server, a format — and it survives a restart. Not for secrets: it is a readable file in the user's state directory, and an API key belongs in their environment. Settings can also be reset from the Settings page, which empties your section with the rest, so always read with a default: a value that is not there is a first run.
7. Listen¶
Named methods, not event strings — episode_opened, episode_closed, show_changed,
retranslate. Override the ones you care about and ignore the rest.
8. Translate yourself¶
Your strings live in locales/*.po beside your code, read through self.t("key"). Podlibre's own
catalogue holds no keys for an extension it has never heard of. The language travels with the
event and your catalogue is reloaded before retranslate() is called, so you only redraw.
9. Test without a window¶
Write the part that thinks separately from the part that draws, and the thinking is testable with no Qt, no show file and no network. The bundled folder publisher keeps its whole feed writer in a module whose only import from Podlibre is the field catalogue it writes by, so its tests hand it values and read the document back.
Giving it to somebody¶
Zip your plugin's folder and they press Add a plugin on the Plugins screen: From a zip file…, and it is copied into their own plugin directory, switched on and loaded without a restart. The folder inside the archive is the id, so zip the folder rather than the files in it — a zip of loose files is named after the archive instead, and a zip of your whole repository works as long as the plugin folder inside it is the only importable one.
They can also point at a folder, which is what you do with your own while you are writing it — and switching your plugin off and on again reloads it from disk, so a change does not need a restart. Each card carries Uninstall for a plugin that was installed rather than shipped: the folder goes, and so does whatever the plugin kept in the settings.
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. Run Podlibre from a terminal while you are working on a plugin, and you will see the file and the reason. One you have just added says so on the Plugins screen as well, with the file and the reason on its card: it is installed, and it is not running.
Related¶
- Hook reference — every hook, every event
- The workflow engine — activities, states, workflows
- The data model — how fields work
- Architecture — where a plugin sits