Skip to content

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:

PySide6   pluggy   requests   numpy   pedalboard   sounddevice   faster-whisper

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. Use self.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

from podlibre import fields as F

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:transcript is 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:

  1. The folder name is your id. It must be importable by Python: 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.
  2. A class whose name ends in Plugin is 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.