If MediaMTX launches your YouTube publishing command through a path’s runOnInit, set runOnInitRestart: yes to have MediaMTX restart that command when it exits. This handles an exited process; it does not detect a process that is still running but hung, and it does not guarantee YouTube will resume the same viewer-facing live event after every interruption.
First identify what actually stopped: the publisher, MediaMTX’s path source, a client connected to MediaMTX, or the YouTube event. Those are different failure points, and the right recovery action depends on which one occurred.
Identify which process stopped
A stream that disappears from YouTube is a symptom, not a diagnosis. MediaMTX may still be running while an external publisher such as FFmpeg has exited. The publisher may still be sending to MediaMTX, while MediaMTX has lost its source. Or both may be working while YouTube has stopped accepting the feed or changed the event’s state.
Start by checking the process list or service manager on the machine running MediaMTX. Is MediaMTX alive? Is the publisher command alive? If the publisher has exited, note its exit message and the time. If it is still present, do not assume that it is sending media: a process can remain alive while stuck waiting on a network operation or otherwise making no progress.
Then check the MediaMTX path state and logs. A path going offline points to a different issue from a publisher that has exited and is being relaunched. Finally, open YouTube Studio for the intended event and inspect the preview or stream status. A local path becoming available again is not proof that YouTube has resumed ingesting or that viewers are seeing the same event.
This distinction is useful for a devotional loop, a study channel, or a local news feed: a local player may recover quickly while the YouTube event still needs attention. Keep a brief incident note with the time, which process changed state, relevant log lines, and what YouTube showed. It makes a one-off interruption easier to separate from a recurring failure.
If your publisher is FFmpeg, the Docker playlist walkthrough can help you understand how a long-running publishing command fits into a looped-video setup. The important point here is to identify the command’s actual owner before changing restart behaviour.
Check how the publishing command was launched
runOnInitRestart applies to a command launched by the path’s runOnInit hook. If you start FFmpeg from a shell, a system service, Docker, a scheduled task, or a separate supervisor, MediaMTX is not necessarily managing that process. Changing the MediaMTX hook settings will not automatically restart a process that MediaMTX did not launch through that hook.
Inspect the configuration for the relevant path and find the command that publishes towards YouTube or supplies the stream. Keep the command, input URL, output settings, and destination intact while diagnosing; replacing them with a generic example risks introducing a second problem. The appropriate FFmpeg options depend on the actual input, codecs, operating system, and output route, so there is no safe universal command to paste in here.
The MediaMTX hooks documentation describes runOnInit and its restart setting. Compare that rolling documentation with the configuration for the version you have deployed: the project pages point to the current main branch, not a manual tied to every possible release. The configuration template is also useful for checking available path options and their spelling.
If another service owns the publisher process, use that service’s documented restart and health-check facilities instead of expecting a MediaMTX path hook to supervise it. Do not run two supervisors against the same command unless you have deliberately designed for that arrangement: they can start duplicate publishers, compete for an input, or obscure which one is responsible for recovery.
Treat the YouTube stream key as a credential. Avoid pasting a full publishing command containing the key into public support threads, screenshots, or logs that are shared without redaction. You can still compare the command structure and error output while hiding the secret value.
Use runOnInitRestart for commands that exit
For a publisher launched by runOnInit, the relevant configuration shape is a path-specific runOnInit command together with runOnInitRestart: yes. MediaMTX runs the command when the path initializes; with the restart option enabled, it can launch the command again after that command exits. Use the exact option names and YAML structure supported by your installed MediaMTX version, and retain your existing command rather than copying a publisher command intended for different inputs or codecs.
That is process recovery, not a diagnosis of why the command exited. If FFmpeg quits because its input vanished, the restart can bring it back, but it may quit again until the input returns. If a destination or credential is wrong, repeated launches do not correct it. Read the command’s output and MediaMTX logs to determine whether a restart is resolving a transient failure or just repeating the same one.
Keep the recovery test controlled. Make a copy of the configuration first, confirm that only one publisher command is active, and use a test event or a period when a brief interruption is acceptable. Verify that the command exits, that MediaMTX starts it again, and that the relaunch reaches the intended destination. Do not infer successful YouTube recovery solely from seeing a new process in the operating system.
For a file-based music or lecture channel, problems can arise in both the loop and the publishing path. The FFmpeg recorded-lecture guide is relevant when you are checking loop behaviour, while a stream-key problem calls for a separate check. The Kirtan stream-key troubleshooting guide covers that distinct failure class; a restart setting cannot make an invalid key valid.
Distinguish disconnect hooks from command restarts
runOnDisconnect is not another name for restarting a publisher. MediaMTX documents it as a hook that runs when a client disconnects from the server. That event tells you about a client’s connection to MediaMTX; by itself it does not mean that the runOnInit command exited or that the YouTube event disconnected.
A practical comparison helps keep the mechanisms separate:
| Mechanism | Event it responds to | What it does not establish |
|---|---|---|
runOnInitRestart: yes |
The command started through runOnInit exits |
That YouTube will resume the same event, or that a hung process will be detected |
runOnDisconnect |
A client disconnects from MediaMTX | That the publisher exited or should be relaunched |
runOnOffline |
A MediaMTX path becomes offline | That an upstream publisher has restarted or YouTube is ingesting |
alwaysAvailable |
A reader requests an offline path | That the publisher or YouTube feed has recovered |
Choose the hook by the event you want to respond to. If you need to run a notification or clean-up command when a client leaves, a disconnect hook may fit. If the requirement is to relaunch an exited command created by runOnInit, use its restart setting. If a path going offline matters for an alert, look at the path-state hooks, but do not treat them as interchangeable process supervision.
The distinction matters in a system with multiple viewers. One viewer can disconnect while the publisher is still sending and other viewers continue watching. Conversely, the publisher can fail while no local reader is connected. A client-disconnect event is not a dependable proxy for the state of the publisher or YouTube ingest.
Inspect logs and test a restart
Look at the MediaMTX log around the interruption and at the publisher’s own standard output and error. Record the order of events: did the path initialize, did the command start, did it exit, and did MediaMTX launch it again? If the publisher is managed outside MediaMTX, check that manager’s logs instead. The purpose is to establish which component acted, not simply to find a line containing the word “disconnect”.
When possible, test in a controlled window or with a separate test event. Confirm the initial publish works before testing recovery. Then stop the publisher cleanly and observe whether MediaMTX relaunches the runOnInit command. A clean exit tests the documented restart path without forcing a network outage or risking a live audience. Afterward check the path and YouTube preview, and confirm that the output is progressing rather than merely connected.
Do not use a production stream key in an experiment that could accidentally create a second publisher or interfere with an active event. If you must test with the real event, coordinate a quiet period and understand how the event is configured first. YouTube’s encoder setup guidance explains the Live server URL and stream key fields; check that the publishing command uses the intended values without exposing the key.
A useful test record includes the MediaMTX version, relevant path settings, the exact command with secrets removed, exit or error text, and the state shown in YouTube Studio. This is more actionable than “it went offline overnight”. It also helps you notice whether recovery is consistent or whether each relaunch encounters the same upstream problem.
The restart option cannot make an invalid destination URL, expired or incorrect key, unavailable input file, or incompatible output format work. If every launch fails in the same way, fix that underlying fault rather than treating more restarts as the solution. Once the command runs, continue checking both MediaMTX and YouTube rather than relying on one green status indicator.
Handle hung processes separately
An exited command and a hung command are different states. runOnInitRestart responds when its managed command exits. It does not, on the evidence documented for this option, detect that a process remains present but has stopped making useful progress. A process that stays alive while the feed is frozen may therefore never trigger this restart behaviour.
For a suspected hang, check more than whether the process exists. Compare its recent log output, whether the MediaMTX path remains online, whether media timestamps or visible video advance, and whether YouTube reports incoming data. The exact monitoring method depends on the publisher and deployment; do not assume a single process-list check proves the feed is healthy.
If you need hung-process recovery, use a separate, deliberately chosen health check or process supervisor that can test the signal you care about and decide what action to take. For example, an operator may monitor whether expected media continues to reach a local path and alert if it stops. The check must be designed to avoid false alarms during normal pauses or input changes. MediaMTX’s command-exit restart is not a substitute for defining that health signal.
Avoid stacking automatic kill-and-relaunch rules before you understand the symptom. A monitor that kills a slow but healthy process can create repeated interruptions, and duplicate supervisors can start overlapping publishers. Start with an alert and a manual test, then add automated intervention only when you know what condition it is detecting and how you will verify recovery.
If you distribute a local slate during source outages, MediaMTX’s alwaysAvailable feature can provide an offline segment to readers of the MediaMTX path. That may reduce a blank local player, but it does not restart the upstream publisher and does not promise that YouTube continues receiving the programme. Keep audience-facing continuity and upstream recovery as separate requirements.
Check the YouTube event after reconnect
A publisher relaunch is only one step in recovery. The command may be running again and sending data, yet YouTube may show a different state from the one you expect. Whether the same event returns, how long the interruption is tolerated, and what viewers see depend on the event and stream settings and the connection outcome. The official material does not support a blanket promise that every reconnect resumes the same viewer-facing live event.
Open the intended event in YouTube Studio and check the preview, incoming stream status, and watch page as appropriate. YouTube’s live streaming tips recommend testing and monitoring stream audio and video; follow the current guidance for the account and event you are using. A process reporting that it has connected to an ingest address is not the same as confirming that the preview has moving video and sound.
Review the event settings before a planned test. YouTube’s stream settings help page describes stream settings and the available start/stop controls. Auto-start and auto-stop affect event behaviour, but should not be read as proof that an interruption will always reconnect to the same watch page. Confirm the intended event behaviour with a test rather than relying on the names of settings.
For a 24/7 channel, decide what a viewer should do if a reconnect does not restore the event: where will you see an alert, who can inspect Studio, and how will you communicate a new watch link if one becomes necessary? A restart rule can shorten the time before a publisher tries again, but a human still needs a way to see whether the actual broadcast recovered. This matters for a bhajan channel overnight just as much as for a small business stream during opening hours.
If your current setup depends on your own computer remaining on to run the publishing command, moving that workload away from the desk can remove that particular operational burden. StreamNeo is relevant when the job is to keep an uploaded video broadcasting to YouTube without leaving your computer running; it is YouTube-only, and it does not replace checking the event’s status after a disruption.
Before committing, compare the operating options on the pricing page. When the file and channel are ready, start free — 24-hour trial, no card.
FAQ
Does runOnInitRestart: yes restart FFmpeg after it disconnects?
It can restart FFmpeg when FFmpeg is the command launched by a path’s runOnInit and that command exits. It is not a general response to every network disconnect, and it does not restart a process that MediaMTX did not launch through that hook. Check the logs to confirm that the command exited and MediaMTX relaunched it.
Does runOnDisconnect restart the stream?
No. It runs when a client disconnects from MediaMTX, which is different from the runOnInit publisher process exiting. Use the restart setting for the latter, and use a disconnect hook only for work tied to a client leaving.
Will YouTube keep the same live stream after reconnect?
There is no blanket guarantee for every event or interruption. Check the event settings, preview, and watch page in YouTube Studio, and test the reconnect behaviour using the event you intend to operate.
Can MediaMTX show a slate while the source is down?
Its alwaysAvailable feature can serve an offline segment to readers of a MediaMTX path. That helps local readers, but it does not restart the upstream publisher or ensure that YouTube continues ingesting the stream.