Skip to content

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:

  1. 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-plugin will not load, and Podlibre says so by name rather than failing later. You do not need an __init__.py.
  2. A class whose name ends with Plugin is the plugin. Inherit from podlibre.plugin.Plugin and 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:

podlibre --plugin-dir .

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.

    steps = [Step("tag_mood", phase="enrich")]

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:

    workflows = [Flow("simple", "Simple",
                      steps=["import_audio", "tag_mood", "metadata"])]

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

    fields = [Field("mood", on="episode", type="choice",
                    choices=("calm", "tense"), shared=True)]

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:

    model = self.settings.get("model", "small")
    self.settings.set("model", "medium")

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

    def episode_opened(self, episode_id, values):
        self.note.setText(values.get("mood", ""))

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.