muvid.subgenres

muvid subgenres — the plugin surface for another kind of video.

muvid’s three parts each know how to make one thing. A subgenre is how a fourth kind gets added — by muvid, or by anyone else — without editing muvid.

from muvid.subgenres import Subgenre, register_subgenre

MY_THING = Subgenre(

slug=”ransom-note”, title=”Ransom note”, description=”Lyrics cut from magazines, one word per beat.”, render=”my_package.render:render”, # a STRING, imported lazily inputs={“type”: “object”, “required”: [“audio”],

“properties”: {“audio”: {“type”: “string”, “format”: “path”}}},

)

Ship it by pointing an entry point at the manifest:

[project.entry-points."muvid.subgenres.v1"]
ransom-note = "my_package.subgenre:MY_THING"

Two things make this worth having over a plain dict:

The entry point’s value is a manifest, not a renderer. Listing every installed subgenre imports no rendering code, so a UI or an LLM can choose among twelve of them in microseconds and a plugin whose heavy dependency is missing degrades to a recorded error instead of taking the catalogue down.

**It composes with nw rather than competing with it.** nw.Genre is the cross-package catalogue a host connector reads; a muvid subgenre is one more nw.Template underneath muvid’s own genre, carrying params={"subgenre": slug}. So a plugin author depends on muvid and nothing else, and the connector picks the plugin up for free.

Where each piece lives:

• muvid.subgenres._manifest — the Subgenre data, stdlib only.

• muvid.subgenres._registry — registration, discovery, resolution.

• muvid.subgenres._contract — the Renderer protocol.

• muvid.subgenres.testing — a conformance kit for plugin authors.

This module imports nothing heavier than the standard library, so import muvid.subgenres is safe on any import-safe path.

Functions

get_subgenre(slug, *[, refresh])	The manifest for slug.
iter_subgenres(*[, refresh])	Iterate manifests in slug order.
list_subgenres(*[, refresh])	Every available subgenre slug, sorted.
register_subgenre(subgenre)	Register a subgenre in this process.
render_subgenre(slug, *, inputs[, params])	Render slug — the one call that imports plugin code.
resolve_renderer(slug)	Import and return the renderer for slug.
subgenre_catalog(*[, refresh])	JSON-able catalogue: what a CLI, an HTTP route, an MCP tool or an agent serves.
unregister_subgenre(slug)	Remove an in-process registration.

Classes

Example(*, description[, params, inputs, ...])	One invocation worth showing to a human or an agent.
RenderRequest(*, subgenre, inputs[, params])	Everything a subgenre renderer gets.
RenderResult(*, output[, duration_s, ...])	What a renderer gives back.
Renderer(*args, **kwargs)	(RenderRequest) -> RenderResult, and nothing else.
Subgenre(*, slug, title, description, render)	A declared kind of video, and how to render one.

class muvid.subgenres.Example(*, description, params=<factory>, inputs=<factory>, preview=None)

Bases: object

One invocation worth showing to a human or an agent.

Agents pick better from examples than from prose — the Remotion registry’s finding, and the reason this is a first-class field rather than something buried in description.

inputs: Mapping[str, Any]

Inputs for this example, when they can be stated without a local path. The conformance kit uses the first Example’s inputs for its trial render.

preview: str | None

Optional path, relative to the plugin package, of a short sample render.

class muvid.subgenres.RenderRequest(*, subgenre, inputs, params=<factory>, workdir, output)

Bases: object

Everything a subgenre renderer gets.

Parameters:

• subgenre (str) – the slug being rendered, so one function can serve several.

• inputs (Mapping[str, Any]) – the caller’s files and primitives, validated against the manifest’s inputs schema before it gets here.

• params (Mapping[str, Any]) – the styling/treatment knobs, validated against params_schema.

• workdir (Path) – a directory the renderer may write intermediates into. It exists, and it belongs to this render — nothing else writes there.

• output (Path) – where the finished artifact must be written.

class muvid.subgenres.RenderResult(*, output, duration_s=None, artifacts=<factory>, meta=<factory>)

Bases: object

What a renderer gives back.

Parameters:

• output (Path) – the finished artifact. Must be the request’s output.

• duration_s (float | None) – length of the produced media, when it has one.

• artifacts (Mapping[str, Path]) – named side products worth keeping — a .ass subtitle file, a thumbnail, the resolved treatment spec. These are how a subgenre stays inspectable instead of producing an opaque file.

• meta (Mapping[str, Any]) – anything else worth recording; must be JSON-able.

class muvid.subgenres.Renderer(*args, **kwargs)

Bases: Protocol

(RenderRequest) -> RenderResult, and nothing else.

class muvid.subgenres.Subgenre(*, slug, title, description, render, inputs=<factory>, params_schema=<factory>, produces='video/mp4', examples=(), intake_kinds=(), cost_profile=None, provider=None, api_versions=())

Bases: object

A declared kind of video, and how to render one.

Everything here is JSON-able except render, which is a reference to a callable rather than the callable itself. Construct one at module scope in a stdlib-only module and point an entry point at it.

Parameters:

• slug (str) – stable id; also a path segment and a public contract value, so choose it once. Lowercase, hyphen-separated.

• inputs (Mapping[str, Any]) – JSON Schema for the files and primitives the renderer needs. One schema serves the UI form, CLI validation and the MCP tool definition, which is why it is a schema and not prose.

• params_schema (Mapping[str, Any]) – JSON Schema for the styling/treatment knobs.

• render (str) – "package.module:function". Imported lazily, once, at render time. The function must satisfy Renderer.

• api_versions (Sequence[str]) – the manifest API versions this plugin is written against. Must include the running API_VERSION.

api_versions: Sequence[str]

a default bound at muvid’s import time would make a plugin that never stated a version “declare” whichever version happens to be running — vacuous for the careless, and it left the careful plugin that pinned “1” refused on a v2 host while the one that pinned nothing sailed through. A plugin states what it was written against; the host decides.

Type:

REQUIRED. No default on purpose

cost_profile: str | None

None means genuinely free. Anything else names a cost estimator, and an unknown cost must force approval rather than encode as zero — see muvid’s conjunctive budget gate.

intake_kinds: Sequence[str]

Free-form tags a host may use to route “what are you making?” answers.

provider: str | None

Which distribution provided this, filled in by the loader for entry-point plugins. None for in-process registrations.

to_dict()

JSON-able form — what a catalogue, a UI or an agent actually reads.

Return type:

dict[str, Any]

muvid.subgenres.get_subgenre(slug, *, refresh=False)

The manifest for slug. Imports no renderer.

Return type:

Subgenre

muvid.subgenres.iter_subgenres(*, refresh=False)

Iterate manifests in slug order.

Return type:

Iterator[Subgenre]

muvid.subgenres.list_subgenres(*, refresh=False)

Every available subgenre slug, sorted. Imports no renderer.

Return type:

list[str]

muvid.subgenres.register_subgenre(subgenre)

Register a subgenre in this process. Returns it, so it can be used inline.

Raises ValueError on a slug collision, matching nw.genres’ on_conflict="error": a slug is a persisted path segment and a public contract value, so silently replacing one is never the kind thing to do.

Return type:

Subgenre

>>> from muvid.subgenres import Subgenre, register_subgenre, list_subgenres
>>> sg = register_subgenre(Subgenre(
...     slug='demo-doctest', title='Demo', description='.',
...     render='muvid.subgenres.testing:echo_renderer', api_versions=("1",)))
>>> 'demo-doctest' in list_subgenres()
True
>>> unregister_subgenre('demo-doctest')

muvid.subgenres.render_subgenre(slug, *, inputs, params=None, workdir, output)

Render slug — the one call that imports plugin code.

Deliberately takes paths and primitives rather than a MusicVideoProject: a plugin coupled to muvid’s project schema would break on every schema change, and could not be driven from a CLI, an HTTP request or an MCP tool without muvid building the project first. A plugin that needs more asks muvid for it through a narrow accessor.

Return type:

RenderResult

muvid.subgenres.resolve_renderer(slug)

Import and return the renderer for slug.

This is the only function in the module that imports plugin code, and it is called at render time, not at listing time.

Return type:

Callable[..., Any]

muvid.subgenres.subgenre_catalog(*, refresh=False)

JSON-able catalogue: what a CLI, an HTTP route, an MCP tool or an agent serves.

Imports no renderer, so this stays cheap however many plugins are installed. load_errors is part of the payload on purpose — a broken plugin should be visible to whoever is choosing, not silently absent.

Return type:

dict[str, Any]

muvid.subgenres.unregister_subgenre(slug)

Remove an in-process registration. Mostly for tests and doctests.

Return type:

None

Modules

testing

A conformance kit for subgenre plugin authors.