Skip to content

Architecture

One process, drawn by Qt, with plugins inside it and anything slow on a thread of its own.

┌──────────────────────────────────────────────────────────────┐
│ Podlibre — one process                                       │
│                                                              │
│  shell · workflow view · episode editor · the Prompt         │
│                           │                                  │
│         ┌─────────────────┴─────────────────┐                │
│         │  pluggy  —  the plugin manager    │                │
│         │  hooks: on_event · activities ·   │                │
│         │         fields · workflows ·      │                │
│         │         uses · answer             │                │
│         └─────────────────┬─────────────────┘                │
│                           │                                  │
│  plugins: audio · filters · transcription · publishing       │
│                                                              │
│  workflow engine · show store · task registry                │
└───────────────────────────┬──────────────────────────────────┘
                            │ a thread per slow job, each a task
                   ┌────────▼────────┐
                   │  decode · fetch │  watched and stoppable
                   │  transcribe     │  from the Tasks tab
                   └─────────────────┘

Plugins

Podlibre's plugin architecture is pluggy, the library pytest, tox and devpi are built on. A plugin framework is a solved problem and this project does not write its own.

A plugin is a folder of Python whose name is its id. Every module in it is imported and every class whose name ends in Plugin is instantiated with the main window and registered. That naming convention is the whole registration mechanism: there is no manifest to keep in sync with the code.

Most plugins inherit podlibre.plugin.Plugin, which implements the hooks from attributes the author declares — steps, fields, workflows, uses — and hands them a page, a thread, a task with a Stop button, their own translations and their own settings. It is a convenience rather than a second architecture: a plugin that wants the hooks raw implements them and inherits nothing.

Plugins do not import one another. They hear each other through a single event hook, so one can be added, removed or replaced without any other knowing it exists. What a plugin contributes to the workflow and to the data model it declares through four more hooks, each typed. The sixth declares nothing: podlibre_answer is Podlibre asking a plugin a question.

Every plugin has a switch. Switching one off unregisters it there and then: it stops hearing events, its page goes, and its steps leave the workflow with it. Two plugins may serve the same step — that is how one replaces another — and the one switched on most recently serves it. See the workflow engine.

See writing a plugin and the hooks.

Components

Component Responsibility
Shell Window, sidebar, header bar, navigation
Workflow view Draws activities and their states; opens steps
Workflow editor Which workflow a show uses, and what is in it
Metadata forms Generated from the field catalogue, so a plugin's field is editable with no interface written for it
Command registry Every action by id; the Prompt and the menus are views of it
Plugin manager Discovery, registration and hook dispatch — pluggy
Event bus One named event reaching every plugin
Task registry Starts, reports, cancels, and times; the Tasks tab is its mirror
Show store The show file: episodes, fields, workflows
Workflow engine Activities, workflows, states; pure logic, no Qt
Settings What the user chose, kept between runs: which plugins are on, which serves a contested step, and a section per plugin

Why it stays responsive

Three rules, and the third is the one that needs discipline:

  1. Anything that might take longer than a frame is a task: it has an id, reports progress and can be cancelled. The Tasks tab, in the drawer at the foot of the window, is the task registry drawn.
  2. A task runs on a thread, and its results come back to the thread that draws through a Qt signal. Nothing touches a widget from a thread.
  3. A plugin that blocks blocks the window. Plugins share this process, so this is a property of the plugins rather than of the structure. It is the cost of the architecture, and it is why both the template and the documentation put threads before anything else.

A plugin that fails to import is reported and skipped, and Podlibre still starts: a missing optional dependency should cost one feature, not the application. A plugin that raises while handling an event is named in the status bar and the others still receive it.

What a plugin may import

Podlibre's own dependencies and the standard library. There is no per-plugin environment and no install step, so a plugin cannot bring a dependency of its own — a plugin that could pull packages in would make any two installations different from each other, and put the licence of whatever it pulled into a GPLv3 application without anyone deciding to.