Independent project · Open source
Virtual RTSP Camera
Repeatable video inputs and failure scenarios for developing and testing video AI systems.
The problem
A healthy camera feed is only one part of testing a video application. Connections drop, pictures freeze, and streams become difficult to decode. Reproducing these conditions with physical cameras can make a simple debugging session depend on hardware and timing.
Virtual RTSP Camera is my open-source tool for turning local recordings into looping RTSP feeds. A developer can connect a video pipeline to those feeds and introduce a specific failure on demand.
How it works
For file-based streams, the tool combines a MediaMTX server with one FFmpeg publisher per camera. Multiple cameras can share a port with separate paths, or use individual ports to represent separate devices.
Compatible video can pass through without re-encoding. Simulations that modify the picture require transcoding. That distinction lets a test use a lightweight input when possible and more processing when the scenario requires it.
A connection that drops and returns
After following the repository's setup instructions, supply a local recording at videos/cam1.mp4 and run the scenario below. The browser playback is compressed, but its states map directly to the documented command.
Flaky simulation · time-compressed playback
Run the fault. Watch the receiver respond.
uv run vcam run -s videos/cam1.mp4 \
--simulation flaky \
--simulation-interval 30 \
--simulation-duration 5# Press “Run scenario” to play the documented flaky-stream behavior.
[00:00] source videos/cam1.mp4 · looping in real time
[00:00] stream rtsp://127.0.0.1:8554/cam1 · available
[00:00] flaky schedule · 30s up / 5s down
[00:00] receiver under test · connected, frames arriving
[00:30] planned flaky event · stream unavailable for 5s
[00:30] receiver under test · connection lost, retrying
[00:35] stream /cam1 · available again
[00:35] receiver under test · reconnected, frames resumed
[00:40] demo window complete · flaky cycle continues
Illustrative output based on the public documentation—not captured CLI logs.
01 Recorded input
cam1.mp4
- Source
- videos/cam1.mp4
- Mode
- Ready to loop
02 RTSP stream
Waiting to start
- Stack
- FFmpeg + MediaMTX
- Endpoint
- 127.0.0.1:8554/cam1
03 Receiver under test
Waiting
Run the scenario to inspect client behavior.
Inspect a state
Configured by the terminal command above: flaky removes the stream after 30s and restores it after 5s.
The receiver state illustrates what to inspect. Reconnection behavior belongs to the application under test.
In this documented scenario, the stream runs for 30 seconds, disappears for 5 seconds, and repeats. Connect the application under test to rtsp://127.0.0.1:8554/cam1.
Observe whether it detects the dropout, releases the disconnected session, and resumes processing when the feed returns. These are behaviors to investigate in the receiving application; the simulator does not establish that the application passes them.
Different failures need different tests
A black picture can still arrive over a valid connection. A network dropout removes the stream itself. The tool keeps those cases separate: blackout produces a valid black video stream, while flaky deliberately disconnects readers.
Other modes introduce noise, degraded encoding, or a picture that stalls. This makes it possible to examine image quality and connection recovery as separate concerns.
Explore the implementation
The public repository includes installation instructions, simulation settings, configuration examples, and tests. The command above is drawn from its documented usage.
Explore the source and documentation ↗