Skip to main content

Media sources

Manage one-based source slots that publish assigned media over RTSP or HTTP MJPEG. A normal workflow is list videos → assign a slot → start it → inspect state → stop it before changing or deleting media.

📄️Assign or clear one source slot

Assigns a media-library path to one one-based source slot. Send an empty `file` value to clear the slot. Insight probes the media, normalizes the requested transport to one supported by the detected codec, persists the assignment, and automatically restarts the source when it was already playing. Obtain valid paths from `/api/mediasrc/videos`. Returns 409 when an external publisher holds the slot and Insight has no stream of its own on it; use `/api/mediasrc/takeover` first. Returns 409 while Insight pulls a network stream into the slot; use `/api/mediasrc/stop` first.

📄️Register one source slot for a browser webcam

Marks one one-based source slot as a browser-published webcam and returns the WHIP URL the browser posts its WebRTC offer to. Unlike `/api/mediasrc/assign`, Insight does not start a publisher itself: the browser publishes the camera over WHIP to an internal ingest path, MediaMTX normalizes it to baseline H.264 with regular keyframes and republishes it on the `urls.rtsp` path (the same shape a file source produces, so detection apps and hardware decoders can consume it directly), and `/api/mediasrc/start` only confirms that the stream arrived. Any file assignment on the slot is cleared, and a playing file source is stopped first. The returned `urls.whip` host and port already account for SDK port remapping, so use it exactly as returned.

📄️Assign available videos to source slots

Convenience operation for test setup. Insight stops every active source, walks the sorted assignable-video list, assigns unique files to source slots in index order, persists the result, and leaves all slots stopped. A slot whose file changes loses its `fps` override, exactly as with a manual assign. Call the bulk-start endpoint afterward when playback should begin. Slots held by an external publisher are skipped and listed in `skipped_external`. Slots Insight is pulling a network stream into are skipped too and listed in `skipped_pulled`.

📄️Start one source

Starts streaming the file assigned to one one-based source slot and persists its state as `playing`. The slot must exist and have a valid assignment. Repeated calls are safe for normal control flows, but callers should inspect `/api/mediasrc` when they need to distinguish newly started from already-running sources. Returns 409 when an external publisher holds the slot and Insight has no stream of its own on it; use `/api/mediasrc/takeover` first. Returns 409 while Insight pulls a network stream into the slot; use `/api/mediasrc/stop` first. When the slot has an `fps` that differs from the media's native frame rate, the matching rendition is created (synchronously, without progress output) or reused before the stream starts; use `/api/mediasrc/prepare` first to observe progress. Because that preparation can take minutes, the slot is re-read afterwards; if another request stopped, reassigned, reset or unassigned it meanwhile, or an external publisher took the slot, the start is abandoned with 409 and nothing is persisted. A start for a slot that a concurrent start already launched succeeds without changing anything.

📄️Prepare the FPS rendition for one source

Creates or reuses the constant-frame-rate rendition that `/api/mediasrc/start` will stream when the slot's `fps` differs from the media's native frame rate. Streams plain-text progress: `Encoding <file> at <fps> fps (<encoder>)...`, `progress <seconds>/<total>` lines, then one of `Rendition ready: <path>`, `Reusing rendition: <path>`, `Source frame rate matches; no rendition needed.` or `Error: <message>`. Renditions are keyed by source content hash, fps, codec and profile, so replacing a source file never reuses an old rendition, while byte-identical files share one rendition that survives until the last of them is deleted or replaced. `/api/mediasrc/start` performs the same preparation without progress output when it is skipped. Returns 409 while Insight pulls a network stream into the slot; use `/api/mediasrc/stop` first.

📄️Stop every source

Stops all running source processes while preserving their file assignments and transport choices. Use this before deleting media, changing a group of assignments, or shutting down a test; the response reports how many sources were previously playing. The external stream on a slot held by an external publisher is left running and the slot is listed in `skipped_external`. A network stream Insight pulls into a slot is stopped like a file source: the slot returns to its previous file assignment and is listed in `stopped_pulled`, and counts toward `stopped_count`. A pull still being set up, or one MediaMTX did not confirm cleared, keeps running and is listed in `skipped_pulled`; stop it again later.

📄️Reset all source assignments

Returns source management to its initial state by stopping every source and rewriting the persisted slot configuration with empty assignments. This is destructive configuration cleanup; use `stop-all` instead when assignments should be retained. The stored record of every slot is cleared, including a slot held by an external publisher; that external stream is left running and its slot is listed in `skipped_external`. A network stream Insight pulls into a slot is stopped like a file source and the slot is listed in `stopped_pulled`. A pull still being set up, or one MediaMTX did not confirm cleared, keeps running and is listed in `skipped_pulled`; stop it again later. Its stored record is cleared either way.

📄️Pull an existing RTSP stream into a slot

Points the slot's mediamtx path at a stream that already exists on the network (an IP camera, another server) so applications read it at `rtsp://…/srcN`. The packets are forwarded unchanged. Only `rtsp://` and `rtsps://` URLs are accepted; credentials go in `username`/`password` or in the URL and never appear in any response. Insight checks the camera once before configuring the pull: rejected credentials answer 400 with `reason: 'auth_failed'` and nothing is configured; an unreachable camera still configures the pull (status `unreachable`) and the slot recovers by itself. The pull is session-only and needs the loopback mediamtx control API.