Skip to content

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 — use say(), 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.