Use FFmpeg Protocols Safely for Files, Pipes and Streams

You will finish with a repeatable way to identify the protocols your FFmpeg build supports, use explicit URLs for files and pipes, and put sensible limits around network input. The examples target the installed FFmpeg 8.0.1 executable on this machine. Allow about fifteen minutes, plus the time needed to identify a real media input if you are testing a network protocol.

You need a shell and FFmpeg. Most examples are ordinary user commands. Writing to a protected directory, binding a listening socket or reading a protected input may require elevated privileges, but this guide does not need sudo. Do not add it just because a media command fails: first check the path, permissions and protocol.

1. Check the executable and its protocol list

Start by checking which binary your shell will run. This matters when a system package and a separately installed build are both present. The protocol list comes from the executable, not from the name of the package you expected to use.

$ command -v ffmpeg
/home/linuxbrew/.linuxbrew/bin/ffmpeg
$ ffmpeg -version | sed -n '1,3p'
ffmpeg version 8.0.1 Copyright (c) 2000-2025 the FFmpeg developers
built with gcc 12 (Ubuntu 12.3.0-1ubuntu1~22.04.2)
configuration: ...
$ ffmpeg -protocols

The last command prints separate input and output lists. A protocol appearing in one list is not automatically usable in the other direction. For example, pipe is useful for streaming media through standard input or output, while file is the normal local filesystem protocol. If a protocol is absent, do not guess its URL syntax: use another available protocol or a build with the required support.

2. Make local file handling explicit

FFmpeg can normally infer the file protocol from a plain path. Prefixing the path with file: makes the intent visible in a script and is useful when explaining a command to someone else.

$ ffmpeg -hide_banner -i file:/path/to/input.mp4 -map 0 -c copy /path/to/output.mkv

This remuxes the input without re-encoding and writes a new Matroska file. Replace both paths with real files. The output is not safe to assume: the file protocol's write option truncates an existing file by default. Test the input first, and choose a new destination while developing a command.

$ ffprobe -hide_banner -v error -show_entries format=format_name,duration -of default=nw=1 file:/path/to/input.mp4
format_name=mov,mp4,m4a,3gp,3g2,mj2
duration=...
$ test -s /path/to/output.mkv && echo 'output is non-empty'

The exact format and duration depend on your media. If the input probe fails, stop there. Check the path with ls -l and confirm that the current user can read it. Do not run the conversion as root to conceal a permissions problem.

3. Use a pipe when another program owns the bytes

The pipe protocol connects FFmpeg to a file descriptor. pipe:0 means standard input and pipe:1 means standard output. This is different from a file path: a pipe is generally not seekable, so formats or operations that require seeking may need a temporary file or the cache: wrapper.

$ producer --output=- | ffmpeg -hide_banner -i pipe:0 -f null -
$ ffmpeg -hide_banner -i file:/path/to/input.mp4 -f matroska pipe:1 > output.mkv

producer is a placeholder for a real program that writes media to standard output. The second command sends Matroska bytes to the shell's redirection target. Check the pipeline's status carefully: in a shell without a pipeline failure policy, the final FFmpeg status can hide an earlier producer failure. If your shell supports it, use set -o pipefail before a pipeline and inspect the resulting status.

For a seek-dependent input, the manpage documents cache:<URL> as a wrapper that stores the stream in a temporary file and provides seeking. It can consume disk space and does not make an unreliable source reliable, so use it only when the input format needs it.

4. Set a boundary for network input

Network URLs such as https://media.example.test/input.ts use the protocols compiled into your build. Network commands can wait, reconnect or consume more data than expected. The generic rw_timeout option applies to protocol read and write operations and is measured in microseconds.

$ ffmpeg -hide_banner -rw_timeout 15000000 -i 'https://media.example.test/input.ts' -c copy output.ts

This sets a fifteen-second I/O timeout for the command. It does not guarantee that the server will respond within fifteen seconds overall, and it does not make a URL trustworthy. Treat URLs, redirects and downloaded media as untrusted input. Prefer HTTPS where the source supports it, and avoid putting credentials in a shell history or process list.

For a live UDP input, the protocol-specific timeout option is also measured in microseconds and applies in read mode. UDP is connectionless and can lose or reorder packets; a successful FFmpeg process does not prove that the stream was complete.

$ ffmpeg -hide_banner -timeout 5000000 -i 'udp://239.0.0.1:5000' -map 0 -c copy capture.ts

Only use a multicast address and port supplied by the network owner. This command can create sustained network traffic and a growing output file. Stop it with Ctrl-C when the capture is complete, then verify the file before deleting any source or temporary data.

5. Restrict nested protocols when required

protocol_whitelist is an input option containing a comma-separated list. It controls which protocols may be used, including protocols nested inside another protocol. ALL permits all protocols, while a name prefixed with - disables that protocol. The default is broad for top-level protocols but nested protocols can still be restricted by the protocol that invokes them.

$ ffmpeg -hide_banner -protocol_whitelist file,crypto -i file:/path/to/input.ts -f null -

Use a narrow list only when you know the input needs those protocols. An error naming a blocked nested protocol means the list is incomplete, not that the media is necessarily corrupt. Do not blindly change the option to ALL for files supplied by someone else: widening the set of permitted protocols can change what an input is allowed to open.

6. Diagnose failures without changing the system

Keep these checks separate from conversion. They are read-only and help distinguish an unavailable protocol from a bad URL, an inaccessible file or a timeout:

$ ffmpeg -protocols | sed -n '/^Input:/,/^Output:/p'
$ ffmpeg -hide_banner -h protocol=file
$ ffmpeg -hide_banner -h protocol=http
$ ffprobe -hide_banner -v error file:/path/to/input.mp4

The protocol help output is build-specific. On this machine, the file protocol reports options including truncate, blocksize, follow and seekable; HTTP reports options including seekable, reconnect controls and proxy handling. Do not copy an option from another host without checking that host's help output.