FFmpegfs

FFmpegfs is a read-only FUSE filesystem that transcodes various audio and video formats to MP4, WebM, and many more on the fly using the FFmpeg library. It thus supports a multitude of input formats and provides access in a variety of common output formats.

This enables seamless access to a multimedia file collection with software and/or hardware that only supports one of the output formats, or allows transcoding files simply via drag-and-drop in a file browser.

📌 Website: https://nschlia.github.io/ffmpegfs/

---

Code Status

| Branch | Build State | | --------------------------------------------------------- | ------------------------------------------------------------ | | master | | | master | | | master | | | master | | | master | |

Packaging Status

---

News

Windows Version

A Windows version of FFmpegfs has frequently been requested; see issue #76 for more information. In essence, this failed because Windows doesn't support FUSE. I discovered WinFSP, which offers everything necessary.

To see what's been done so far, checkout the windows branch.

---

New in 2.18

• Feature: Added ALAC profile for iTunes (--desttype=ALAC --profile=ITUNES). Playback of the file will not commence until it is fully recoded; however, it can be played in iTunes.
• Feature: Implemented a validation check for the combination of TYPE and PROFILE in --desttype=TYPE --profile=PROFILE.
• Updated Dockerfile to include FUSE 3.
• Bugfix: Fix error with new FFmpeg API: "Option 'pix_fmts' is not a runtime option and so cannot be set after the object has been initialized".
• Fixed deprecation: Replace avcodec_get_supported_config().
• Fixed deprecation: Remove avcodec_close().
• Fixed deprecation: Remove av_format_inject_global_side_data().
• Fixed deprecation: Replace std::codecvt with iconv in read_file.
• Bugfix: reserve() only guarantees capacity, not size → writing via .data() is undefined behaviour. Using resize() makes the memory usable.
• As strerror() is not thread-safe, use strerror_r() where available.
• strncpy likes to copy without NUL → terminate explicitly.
• Bugfix: Issue #173: Fixed output directory no showing complete list of files under Debian 13.
• Bugfix: Updated Dockerfile for Trixie

---

New in 2.17 (2024-11-10)

• Bugfix: Issue #164: Fixed incorrectly discarded HLS seek requests.
• Bugfix: Wrong error message fixed when an invalid audio/video codec was selected. The message should rather say "unsupported codec" instead of talking about "sample format not supported.".
• Bugfix: Issue #162: If not present, add time stamps to the copied streams.
• Changed quality from 34 to 40 for hardware encoded video streams to create slightly smaller files.
• Closes#1084487:: Moved from the FUSE 2 to the FUSE 3 API.

📜 See HISTORY.md for the complete changelog.

---

Supported Formats

Input

Making a full list of the formats the FFmpeg API supports would be somewhat pointless. See Demuxers on FFmpeg's home pages and Supported Formats on Wikipedia to get an idea.

Sadly, it also depends on the codecs that have been built into the Linux distribution's library. Some, like openSUSE, only include royalty-free codecs, while others, like Red Hat, completely omit FFmpeg. You can use the following command to find out:

ffmpeg -formats

A list of the available codecs will be created as a result. In the case of missing codecs or no FFmpeg at all, your only option is to build FFmpeg yourself. Big fun...

Output

As output, only formats that can be read while being written to can be used. Whereas MP4 is not one of them, it can be supported through the use of format extensions.

Audio Formats

| Format | Description | Audio | | ------------- | ------------- | ------------- | | AIFF | Audio Interchange File Format | PCM 16 bit BE | | ALAC | Apple Lossless Audio Codec | ALAC | | FLAC | Free Lossless Audio | FLAC | | MP3 | MPEG-2 Audio Layer III | MP3 | | Opus |Opus Audio| Opus | | WAV | Waveform Audio File Format | PCM 16 bit LE |

Video Formats

| Format | Description | Video | Audio | | ------------- | ------------- | ------------- | ------------- | | HLS | HTTP Live Streaming | H264 | AAC | | MOV | QuickTime File Format | H264 | AAC | | MP4 | MPEG-4 | H264 | AAC | | OGG|Free Open Container Format| Theora | Vorbis | | ProRes | Apple ProRes | ProRes | PCM 16 bit LE | | TS | MPEG Transport Stream | H264 | AAC | | WebM|Free Open Web Media Project| VP9 | Opus |

Stills

| Format | Description | Video | | ------------- | ------------- | ------------- | | BMP | Video to frameset |BMP| | JPG | Video to frameset |JPEG| | PNG | Video to frameset |PNG|

What can it do?

You can use a collection of several media files with software and/or hardware that only supports one of the permitted output formats or convert files using simple drag-and-drop operations in a file browser with FFmpegfs.

Choose WebM or MP4 for live streaming for the best results. While MP3 will work if video transcoding is not needed, WebM and MP4 produce superior results. The OGG encoder is too slow for real-time file recoding.

All the frames from a video source file will be displayed in a virtual directory called after the source file when a destination of JPG, PNG, or BMP is selected. Audio will not be available.

By choosing HLS, TS segments and an M3U playlist (master.m3u8 and index_0_av.m3u8) are created in a directory. A generated hls.html file that can be accessed in a browser can also be used to play the segments.

Please be aware that since most browsers cannot open the files from disc due to restrictions, they must be on a web server. For further information, see problems.

---

Installation Instructions

A rather detailed description can be found under install.

---

Fixing Problems

This part has been transferred to a different file because it has gotten too big. Details can be found in problems.

---

Usage

Mount your file system as follows:

ffmpegfs [--audiobitrate bitrate] [--videobitrate bitrate] musicdir mountpoint [-o fuse_options]

To use FFmpegfs as a daemon and encode to MPEG-4, for instance:

ffmpegfs --audiobitrate=256K --videobitrate=1.5M /mnt/music /mnt/ffmpegfs -o allow_other,ro,desttype=mp4

This will run FFmpegfs in the foreground and print the log output to the screen:

ffmpegfs -f --log_stderr --audiobitrate=256K --videobitrate=1.5M --audiobitrate=256K --videobitrate=1.5M /mnt/music /mnt/ffmpegfs -o allow_other,ro,desttype=mp4

With the following entry in "/etc/fstab," the same result can be obtained with more recent versions of FUSE:

ffmpegfs#/mnt/music /mnt/ffmpegfs fuse allow_other,ro,audiobitrate=256K,videobitrate=2000000,desttype=mp4 0 0

Another (more current) way to express this command:

/mnt/music /mnt/ffmpegfs fuse.ffmpegfs allow_other,ro,audiobitrate=256K,videobitrate=2000000,desttype=mp4 0 0

At this point, files like /mnt/music/**.flac and /mnt/music/**.ogg will show up as /mnt/ffmpegfs/**.mp4.

Audio bitrates will be reduced to 256 KBit, video to 1.5 MBit. The source bitrate will not be scaled up if it is lower; it will remain at the lower value.

Keep in mind that only root can, by default, use the "allow_other" option. Either use the "user_allow_other" key in /etc/fuse.conf or run FFmpegfs as root.

Any user must have "allow_other" enabled in order to access the mount. By default, only the user who initiated FFmpegfs has access to this.

Examples:

ffmpegfs -f $HOME/test/in $HOME/test/out --log_stderr --log_maxlevel=DEBUG -o allow_other,ro,desttype=mp4,cachepath=$HOME/test/cache

Transcode files using FFmpegfs from test/in to test/out while logging to stderr at a noisy DEBUG level. The cache resides in test/cache. All directories are under the current user's home directory.

 ffmpegfs -f $HOME/test/in $HOME/test/out --log_stderr --log_maxlevel=DEBUG -o allow_other,ro,desttype=mp4,cachepath=$HOME/test/cache,videowidth=640

Similar