muvid.footage.errors

The refusal and cancellation types of the footage operations (muvid.footage.service).

An operation that will not do what it was asked — no song yet, an unknown clip, an edit that does not validate, an alignment nobody vouches for — raises FootageError with a message that names the next action. Every surface turns it into its own refusal: the MCP tools into a fastmcp ToolError, a host’s HTTP route into a 422. The operations never import a transport’s error type, which is what lets one function serve every surface.

An operation a host asked to stop (its should_cancel said so) raises FootageCancelled — not a refusal and not a failure.

How a host tells them apart. nw defines the contract a host reads: nw.GenreOpRefused (a deliberate refusal; everything else out of an op is a bug) and nw.GenreOpCancelled. These two derive from them when nw is importable — the only case in which anything serves the ops generically — and otherwise from ValueError and Exception, because muvid’s core does not depend on nw (it is the mcp extra’s). Either way FootageError is a ValueError, so code already catching that keeps working.

Exceptions

FootageError	An operation refused — the message says why and what to do next.
FootageCancelled	An operation stopped between steps because its host asked it to.

exception muvid.footage.errors.FootageCancelled

Bases: Exception

An operation stopped between steps because its host asked it to.

exception muvid.footage.errors.FootageError

Bases: ValueError

An operation refused — the message says why and what to do next.