Provided by: ffmpegfs_2.15-1build2_amd64 
NAME
ffmpegfs - mounts and transcodes a multitude of formats to one of the target formats on the fly.
SYNOPSIS
ffmpegfs [OPTION]... IN_DIR OUT_DIR
DESCRIPTION
The ffmpegfs(1) command will mount the directory IN_DIR on OUT_DIR. Thereafter, accessing OUT_DIR will
show the contents of IN_DIR, with all supported media files transparently renamed and transcoded to one
of the supported target formats upon access.
Supported output formats:
┌────────┬────────────────────────┬────────┬───────────────┐
│ │ │ │ │
│ Format │ Description │ Audio │ Video │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ AIFF │ Audio Interchange File │ │ PCM 16 bit BE │
│ │ Format │ │ │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ ALAC │ Apple Lossless Audio │ │ ALAC │
│ │ Codec │ │ │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ FLAC │ Free Lossless Audio │ │ FLAC │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ HLS │ HTTP Live Streaming │ H264 │ AAC │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ MOV │ QuickTime File Format │ H264 │ AAC │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ MP3 │ MPEG-2 Audio Layer III │ │ MP3 │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ MP4 │ MPEG-4 │ H264 │ AAC │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ OGG │ │ Theora │ Vorbis │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ MKV │ Matroska │ H264 │ AAC │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ Opus │ │ Opus │ │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ ProRes │ Apple ProRes │ ProRes │ PCM 16 bit LE │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ TS │ MPEG Transport Stream │ H264 │ AAC │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ WAV │ Waveform Audio File │ │ PCM 16 bit LE │
│ │ Format │ │ │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ WebM │ │ VP9 │ Opus │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ BMP │ Video to frameset │ │ BMP │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ JPG │ Video to frameset │ │ JPEG │
├────────┼────────────────────────┼────────┼───────────────┤
│ │ │ │ │
│ PNG │ Video to frameset │ │ PNG │
└────────┴────────────────────────┴────────┴───────────────┘
OPTIONS
Usage: ffmpegfs [OPTION]... IN_DIR OUT_DIR
Mount IN_DIR on OUT_DIR, converting audio and video files upon access.
Encoding options
--desttype=TYPE, -odesttype=TYPE
Select the destination format. TYPE can currently be:
AIFF, ALAC, BMP, FLAC, HLS, JPG, MOV, MP3, MP4, MKV, OGG, Opus, PNG, ProRes, TS, WAV, WebM.
To stream videos, MP4, TS, HLS, OGG, WEBM, MKV, or MOV/PRORES must be selected.
To use HTTP Live Streaming, set HLS.
When a destination JPG, PNG, or BMP is chosen, all frames of a video source file will be presented in
a virtual directory named after the source file. Audio will not be available.
To use the smart transcoding feature, specify a video and audio file type, separated by a "+" sign.
For example, --desttype=mov+aiff will convert video files to Apple Quicktime MOV and audio-only files
to AIFF.
Defaults to: mp4
--audiocodec=TYPE, -oaudiocodec=TYPE
Select an audio codec. TYPE depends on the destination format and can currently be:
┌─────────┬───────────────┐
│ Formats │ Audio Codecs │
├─────────┼───────────────┤
│ MP4 │ AAC, MP3 │
├─────────┼───────────────┤
│ WebM │ OPUS, VORBIS │
├─────────┼───────────────┤
│ MOV │ AAC, AC3, MP3 │
├─────────┼───────────────┤
│ MKV │ AAC, AC3, MP3 │
├─────────┼───────────────┤
│ TS, HLS │ AAC, AC3, MP3 │
└─────────┴───────────────┘
Other destination formats do not support other codecs than the default.
Defaults to: The destination format’s default setting, as indicated by the first codec name in the
list.
--videocodec=TYPE, -ovideocodec=TYPE
Select a video codec. TYPE depends on the destination format and can currently be:
┌─────────┬──────────────────────────┐
│ Formats │ Video Codecs │
├─────────┼──────────────────────────┤
│ MP4 │ H264, H265, MPEG1, MPEG2 │
├─────────┼──────────────────────────┤
│ WebM │ VP9, VP8, AV1 │
├─────────┼──────────────────────────┤
│ MOV │ H264, H265, MPEG1, MPEG2 │
├─────────┼──────────────────────────┤
│ MKV │ H264, H265, MPEG1, MPEG2 │
├─────────┼──────────────────────────┤
│ TS, HLS │ H264, H265, MPEG1, MPEG2 │
└─────────┴──────────────────────────┘
Other destination formats do not support other codecs than the default.
Defaults to: The destination format’s default setting, as indicated by the first codec name in the
list.
--autocopy=OPTION, -oautocopy=OPTION
Select the auto copy option. OPTION can be:
┌─────────────┬───────────────────────────────────────┐
│ OFF │ Never copy streams, transcode always. │
├─────────────┼───────────────────────────────────────┤
│ MATCH │ Copy stream if target supports codec. │
├─────────────┼───────────────────────────────────────┤
│ MATCHLIMIT │ Same as MATCH, only copy if target │
│ │ not larger, transcode otherwise. │
├─────────────┼───────────────────────────────────────┤
│ STRICT │ Copy stream if codec matches desired │
│ │ target, transcode otherwise. │
├─────────────┼───────────────────────────────────────┤
│ STRICTLIMIT │ Same as STRICT, only copy if target │
│ │ not larger, transcode otherwise. │
└─────────────┴───────────────────────────────────────┘
This can speed up transcoding significantly as copying streams uses much less computing power as
compared to transcoding.
MATCH copies a stream if the target supports it, e.g., an AAC audio stream will be copied to MPEG,
although FFmpeg’s target format is MP3 for this container. H264 would be copied to ProRes, although
the result would be a regular MOV or MP4, not a ProRes file.
STRICT would convert AAC to MP3 for MPEG or H264 to ProRes for Prores files to strictly adhere to the
output format setting. This will create homogenous results which might prevent problems with picky
playback software.
Defaults to: OFF
--recodesame=OPTION, -orecodesame=OPTION
Select recode to the same format option, OPTION can be:
┌─────┬───────────────────────────────────┐
│ NO │ Never recode to the same format. │
├─────┼───────────────────────────────────┤
│ YES │ Always recode to the same format. │
└─────┴───────────────────────────────────┘
Defaults to: NO
--profile=NAME, -oprofile=NAME
Set profile for target audience, NAME can be:
┌─────────┬───────────────────────────────────┐
│ NONE │ no profile │
├─────────┼───────────────────────────────────┤
│ FF │ optimise for Firefox │
├─────────┼───────────────────────────────────┤
│ EDGE │ optimise for MS Edge and Internet │
│ │ Explorer > 11 │
├─────────┼───────────────────────────────────┤
│ IE │ optimise for MS Edge and Internet │
│ │ Explorer ⇐ 11 │
├─────────┼───────────────────────────────────┤
│ CHROME │ Google Chrome │
├─────────┼───────────────────────────────────┤
│ SAFARI │ Apple Safari │
├─────────┼───────────────────────────────────┤
│ OPERA │ Opera │
├─────────┼───────────────────────────────────┤
│ MAXTHON │ Maxthon │
└─────────┴───────────────────────────────────┘
Note: applies to the MP4 output format only, and is ignored for all other formats.
Defaults to: NONE
--level=NAME, -o level=NAME
Set level for output if available. NAME can be:
┌──────────┬─────────────────┐
│ PROXY │ Proxy – apco │
├──────────┼─────────────────┤
│ LT │ LT – apcs │
├──────────┼─────────────────┤
│ STANDARD │ standard – apcn │
├──────────┼─────────────────┤
│ HQ │ HQ - apch │
└──────────┴─────────────────┘
Note: applies to the MP4 output format only, and is ignored for all other formats.
Defaults to: HQ
--include_extensions=LIST, -oinclude_extensions=LIST
Set the list of file extensions to be encoded. LIST can have one or more entries that are separated
by commas. These are the only file extensions that will be transcoded. Can be specified numerous
times and will be merged, which is required when specifying them in the fstab because commas cannot
be used to separate the extensions. The entries support shell wildcard patterns.
Example: --include_extensions=mp4,wmv to encode MPEG-4 and Windows Media files only.
Defaults to: Encode all supported files.
--hide_extensions=LIST, -ohide_extensions=LIST
Set a list of file extensions to exclude from the output. LIST can have one or more entries that are
separated by commas. Can be specified numerous times and will be merged, which is required when
specifying them in the fstab because commas cannot be used to separate the extensions. The entries
support shell wildcard patterns.
Example: --hide_extensions=jpg,png,cue to stop covers and cue sheets from showing up.
Defaults to: Show all files.
Audio Options
--audiobitrate=BITRATE, -o audiobitrate=BITRATE
Select the audio encoding bitrate.
Defaults to: 128 kbit
Acceptable values for BITRATE:
mp4: 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160, 176, 192, 224, 256, 288, 320, 352,
384, 416, and 448 kbps.
mp3: For sampling frequencies of 32, 44.1, and 48 kHz, BITRATE can be among 32, 40, 48, 56, 64, 80,
96, 112, 128, 160, 192, 224, 256, and 320 kbps.
For sampling frequencies of 16, 22.05, and 24 kHz, BITRATE can be among 8, 16, 24, 32, 40, 48, 56,
64, 80, 96, 112, 128, 144, and 160 kbps.
When in doubt, it is recommended to choose a bitrate among 96, 112, 128, 160, 192, 224, 256, and 320
kbps.
BITRATE
can be defined as...
• n bit/s: # or #bps
• n kbit/s: #K or #Kbps
• n Mbit/s: #M or #Mbps
--audiosamplerate=SAMPLERATE, -o audiosamplerate=SAMPLERATE
This limits the output sample rate to SAMPLERATE. If the source file sample rate is higher, it will
be downsampled automatically.
Typical values are 8000, 11025, 22050, 44100, 48000, 96000, and 192000.
If the target codec does not support the selected sample rate, the next matching rate will be chosen
(e.g. if 24K is selected but only 22.05 or 44.1 KHz is supported, 22.05 KHz will be set).
Set to 0 to keep the source rate.
Defaults to: 44.1 kHz
SAMPLERATE
can be defined as...
• In Hz: # or #Hz
• In kHz: #K or #KHz
--audiochannels=CHANNELS, -o audiochannels=CHANNELS
This limits the number of output channels to CHANNELS. If the source has more channels, the number
will be reduced to this limit.
Typical values are 1, 2 or 6 (e.g., 5.1) channels.
If the target codec does not support the selected number of channels, transcoding may fail.
Set to 0 to keep the number of channels.
Defaults to: 2 channels (stereo)
--audiosamplefmt=SAMPLEFMT, -o audiosamplefmt=SAMPLEFMT
This sets a sample format. SAMPLEFMT can be:
0 to use the predefined setting; 8, 16, 32, 64 for integer format, F16, F32, F64 for floating point.
Not all formats are supported by all destination types. Selecting an invalid format will be reported
as a command line error and a list of values printed.
┌──────────────────┬─────────────────────────────────┐
│ Container Format │ Sample Format │
├──────────────────┼─────────────────────────────────┤
│ AIFF │ 0, 16, 32 │
├──────────────────┼─────────────────────────────────┤
│ ALAC │ 0, 16, 24 │
├──────────────────┼─────────────────────────────────┤
│ WAV │ 0, 8, 16, 32, 64, F16, F32, F64 │
├──────────────────┼─────────────────────────────────┤
│ FLAC │ 0, 16, 24 │
└──────────────────┴─────────────────────────────────┘
Defaults to: 0 (Use the same as the source or the predefined format of the destination if the source
format is not possible.)
Video Options
--videobitrate=BITRATE, -o videobitrate=BITRATE
This sets the video encoding bit rate. Setting this too high or too low may cause transcoding to
fail.
Defaults to: 2 Mbit
mp4: May be specified as 500 to 25,000 kbps.
BITRATE
can be defined as...
• n bit/s: # or #bps
• n kbit/s: #K or #Kbps
• n Mbit/s: #M or #Mbps
--videoheight=HEIGHT, -o videoheight=HEIGHT
This sets the height of the transcoded video.
When the video is rescaled, the aspect ratio is preserved if --width is not set at the same time.
Defaults to: keep source video height
--videowidth=WIDTH, -o videowidth=WIDTH
This sets the width of the transcoded video.
When the video is rescaled, the aspect ratio is preserved if --height is not set at the same time.
Defaults to: keep source video width
--deinterlace, -o deinterlace
Deinterlace video if necessary while transcoding.
This may need a higher bit rate, but this will increase picture quality when streaming via HTML5.
Defaults to: "no deinterlace"
HLS Options
--segment_duration, -o segment_duration
Set the duration of one video segment of the HLS stream. This argument is a floating point value,
e.g., it can be set to 2.5 for 2500 milliseconds.
Should normally be left as the default.
Note: This applies to the HLS output format only, and is ignored for all other formats.
Defaults to: 10 seconds
--min_seek_time_diff, -o min_seek_time_diff
If the requested HLS segment is less than min_seek_time seconds away, discard the seek request. The
segment will be available very soon anyway, and that makes a re-transcode necessary. Set to 0 to
disable.
Should normally be left as the default.
Note: This applies to the HLS output format only, and is ignored for all other formats.
Defaults to: 30 seconds
Hardware Acceleration Options
--hwaccel_enc=API, -o hwaccel_enc=API
Select the hardware acceleration API for encoding.
Defaults to: NONE (no acceleration).
API
can be defined as...
• NONE: use software encoder
• VAAPI: Video Acceleration API (VA-API)
• OMX: OpenMAX (Open Media Acceleration)
--hwaccel_dec_blocked=CODEC[:PROFILE[:PROFILE]], -o hwaccel_dec_blocked=CODEC:[:PROFILE[:PROFILE]]
Block a codec and, optionally, a profile for hardware decoding. The option can be repeated to block
several codecs.
Defaults to: no codecs blocked.
CODEC
can be defined as...
• H263: H.263
• H264: H.264
• HEVC: H.265 / HEVC
• MPEG2: MPEG-2 video
• MPEG4: MPEG-4 video
• VC1: SMPTE VC-1
• VP8: Google VP9
• VP9: Google VP9
• WMV3: Windows Media Video 9
PROFILE
can optionally be added to block a certain profile from the codec only.
Example: VP9:0 blocks Google VP profile 0.
Example: H264:1:33 blocks H.264 profile 1 and 33.
--hwaccel_enc_device=DEVICE, -o hwaccel_enc_device=DEVICE
Select the hardware acceleration device. May be required for VAAPI, especially if more than one
device is available.
Note: This only applies to VAAPI hardware acceleration; all other types are ignored.
Defaults to: empty (use default device).
Example: /dev/dri/renderD128
--hwaccel_dec=API, -o hwaccel_dec=API
Select the hardware acceleration API for decoding.
Defaults to: NONE (no acceleration)
API
can be defined as...
• NONE: use software decoder
• VAAPI: Video Acceleration API (VA-API)
• MMAL: Multimedia Abstraction Layer by Broadcom
--hwaccel_dec_device=DEVICE, -o hwaccel_dec_device=DEVICE
Select the hardware acceleration device. May be required for VAAPI, especially if more than one
device is available.
Note: This only applies to VAAPI hardware acceleration; all other types are ignored.
Defaults to: empty (use default device)
Example: /dev/dri/renderD128
Album Arts
--noalbumarts, -o noalbumarts
Do not copy album art into the output file.
This will reduce the file size and may be useful when streaming via HTML5 when album art is not used
anyway.
Defaults to: add album arts
Virtual Script
--enablescript, -o enablescript
Add a virtual index.php to every directory. It reads scripts/videotag.php from the FFmpegfs binary
directory.
This can be very handy for testing video playback. Of course, feel free to replace videotag.php with
your own script.
Defaults to: Do not generate script file
--scriptfile, -o scriptfile
Set the name of the virtual script created in each directory.
Defaults to: index.php
--scriptsource, -o scriptsource
Use a different source file.
Defaults to: scripts/videotag.php
Cache Options
--expiry_time=TIME, -o expiry_time=TIME
Cache entries expire after TIME and will be deleted to save disc space.
Defaults to: 1 week
--max_inactive_suspend=TIME, -o max_inactive_suspend=TIME
While being accessed, the file is transcoded to the target format in the background. When the client
quits, transcoding will continue until this time out. Transcoding is suspended until it is accessed
again, then transcoding will continue.
Defaults to: 15 seconds
--max_inactive_abort=TIME, -o max_inactive_abort=TIME
While being accessed, the file is transcoded in the background to the target format. When the client
quits, transcoding will continue until this time out, then the transcoder thread quits.
Defaults to: 30 seconds
--prebuffer_time=TIME, -o prebuffer_time=TIME
Files will be decoded until the buffer contains the specified playing time, allowing playback to
start smoothly without lags. Both options must be met if prebuffer time and prebuffer size are
specified.
Set to 0 to disable pre-buffering.
Defaults to: no prebuffer time
--prebuffer_size=SIZE, -o prebuffer_size=SIZE
Files will be decoded until the specified number of bytes is present in the buffer, allowing playback
to start smoothly without lags. Both options must be met if prebuffer size and prebuffer time are
specified.
Set to 0 to disable pre-buffering.
Defaults to: 100 KB
--max_cache_size=SIZE, -o max_cache_size=SIZE
Set the maximum diskspace used by the cache. If the cache grows beyond this limit when a file is
transcoded, old entries will be deleted to keep the cache within the size limit.
Defaults to: unlimited
--min_diskspace=SIZE, -o min_diskspace=SIZE
Set the required diskspace on the cachepath mount. If the remaining space falls below SIZE when a
file is transcoded, old entries will be deleted to keep the diskspace within the limit.
Defaults to: 0 (no minimum space)
--cachepath=DIR, -o cachepath=DIR
Sets the disc cache directory to DIR. If it does not already exist, it will be created. The user
running FFmpegfs must have write access to the location.
Defaults to: ${XDG_CACHE_HOME:-~/.cache}/ffmpegfs (as specified in the XDG Base Directory
Specification). Falls back to ${HOME:-~/.cache}/ffmpegfs if not defined. If executed with root
privileges, "/var/cache/ffmpegfs" will be used.
--disable_cache, -o disable_cache
Disable the cache functionality completely.
Defaults to: enabled
--cache_maintenance=TIME, -o cache_maintenance=TIME
Starts cache maintenance in TIME intervals. This will enforce the expery_time, max_cache_size and
min_diskspace settings. Do not set it too low as this can slow down transcoding.
Only one FFmpegfs process will do the maintenance by becoming the master. If that process exits,
another will take over, so that one will always do the maintenance.
Defaults to: 1 hour
--prune_cache
Prune the cache immediately according to the above settings at application start up.
Defaults to: Do not prune cache
--clear_cache, -o clear_cache
On startup, clear the cache. All previously transcoded files will be deleted.
TIME
can be defined as...
• Seconds: #
• Minutes: #m
• Hours: #h
• Days: #d
• Weeks: #w
SIZE
can be defined as...
• In bytes: # or #B
• In KBytes: #K or #KB
• In MBytes: #M or #MB
• In GBytes: #G or #GB
• In TBytes: #T or #TB
Other
--max_threads=COUNT, -o max_threads=COUNT
Limit concurrent transcoder threads. Set to 0 for unlimited threads. Recommended values are up to 16
times the number of CPU cores. Should be left as the default.
Defaults to: 16 times number of detected cpu cores
--decoding_errors, -o decoding_errors
Decoding errors are normally ignored, leaving bloopers and hiccups in encoded audio or video but
still creating a valid file. When this option is set, transcoding will stop with an error.
Defaults to: Ignore errors
--min_dvd_chapter_duration=SECONDS, -o min_dvd_chapter_duration=SECONDS
This ignores DVD chapters shorter than SECONDS. To disable, set to 0. This avoids transcoding errors
for DVD chapters too short to detect its streams.
Defaults to: 1 second
--win_smb_fix, -o win_smb_fix
Windows seems to access the files on Samba drives starting at the last 64K segment when the file is
opened. Setting --win_smb_fix=1 will ignore these attempts (not decode the file up to this point).
Defaults to: on
Logging
--log_maxlevel=LEVEL, -o log_maxlevel=LEVEL
Maximum level of messages to log, either ERROR, WARNING, INFO, DEBUG or TRACE. Defaults to INFO and
is always set to DEBUG in debug mode.
Note that the other log flags must also be set to enable logging.
--log_stderr, -o log_stderr
Enable outputting logging messages to stderr. Automatically enabled in debug mode.
--log_syslog, -o log_syslog
Enable outputting logging messages to syslog.
--logfile=FILE, -o logfile=FILE
File to output log messages to. By default, no file will be written.
General/FUSE options
-d, -o debug
Enable debug output. This will result in a large quantity of diagnostic information being printed to
stderr as the programme runs. It implies -f.
-f
Run in the foreground instead of detaching from the terminal.
-h, --help
Print usage information.
-V, --version
Output version information.
-c, --capabilities
Output FFmpeg capabilities: a list of the system’s available codecs.
-s
Force single-threaded operation.
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, utilise 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 TRACE 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 to the previous, but with a 640-pixel maximum video width. The aspect ratio will be maintained
when scaling down larger videos. Videos that are smaller won’t be scaled up.
ffmpegfs -f $HOME/test/in $HOME/test/out --log_stderr --log_maxlevel=DEBUG -o allow_other,ro,desttype=mp4,cachepath=$HOME/test/cache,deinterlace
Deinterlacing can be enabled for better image quality.
HOW IT WORKS
The decoder and encoder are initialised when a file is opened, and the file’s metadata is also read. At
this point, a rough estimate of the total file size can be made. Because the actual size greatly depends
on the material encoded, this technique works fair-to-good for MP4 or WebM output files but works well
for MP3, AIFF, or WAV output files.
The file is transcoded as it is being read and stored in a private per-file buffer. This buffer keeps
expanding as the file is read until the entire file has been transcoded. After being decoded, the file is
stored in a disc buffer and is readily accessible.
Other processes will share the same transcoded data if they access the same file because transcoding is
done in a single additional thread, which saves CPU time. Transcoding will continue for a while if all
processes close the file before it is finished. Transcoding will resume if the file is viewed once more
before the timer expires. If not, it will halt and delete the current chunk to free up storage space.
A file will be transcoded up to the seek point when you seek within it (if not already done). Since the
majority of programmes will read a file from beginning to end, this is typically not a problem. Future
upgrades might offer actual random seeking (but if this is feasible, it is not yet clear due to
restrictions to positioning inside compressed streams). When HLS streaming is chosen, this already
functions. The requested segment is immediately skipped to by FFmpegfs.
MP3: The source file’s comments are used to generate ID3 version 2.4 and 1.1 tags. They are
correspondingly at the beginning and the end of the file.
MP4: The same is true for meta atoms contained in MP4 containers.
WAV: The estimated size of the WAV file will be included in a pro forma WAV header. When the file is
complete, this header will be changed. Though most current gamers apparently disregard this information
and continue to play the file, it does not seem required.
Only for MP3 targets: A particular optimization has been done so that programmes that look for id3v1 tags
don’t have to wait for the entire file to be transcoded before reading the tag. This accelerates these
apps dramatically.
ABOUT OUTPUT FORMATS
A few remarks regarding the output formats that are supported:
Since these are plain vanilla constant bitrate (CBR) MP3 files, there isn’t much to say about the MP3
output. Any modern player should be able to play them well.
However, MP4 files are unique because standard MP4s aren’t really ideal for live broadcasting. The start
block of an MP4 has a field with the size of the compressed data section, which is the cause. It suffices
to say that until the size is known, compression must be finished, a file seek must be performed to the
beginning, and the size atom updated.
That size is unknown for a live stream that is ongoing. To obtain that value for our transcoded files,
one would need to wait for the entire file to be recoded. As if that weren’t enough, the file’s final
section contains some crucial details, such as meta tags for the artist, album, etc. Additionally, the
fact that there is just one enormous data block makes it difficult to do random searches among the
contents without access to the entire data section.
Many programmes will then read the crucial information from the end of an MP4 before returning to the
file’s head and beginning playback. This will destroy FFmpegfs' entire transcode-on-demand concept.
Several extensions have been created to work around the restriction, including "faststart," which moves
the aforementioned meta data from the end to the beginning of the MP4 file. Additionally, it is possible
to omit the size field (0). An further plugin is isml (smooth live streaming).
Older versions of FFmpeg do not support several new MP4 features that are required for direct-to-stream
transcoding, like ISMV, faststart, separate moof/empty moov, to mention a few (or if available, not
working properly).
Faststart files are produced by default with an empty size field so that the file can be started to be
written out at once rather than having to be encoded as a complete first. It would take some time before
playback could begin if it were fully encoded. The data part is divided into chunks of about 1 second
each, all with their own header, so it is possible to fill in the size fields early enough.
One disadvantage is that not all players agree with the format, or they play it with odd side effects.
VLC only refreshes the time display every several seconds while playing the file. There may not always be
a complete duration displayed while streaming using HTML5 video tags, but that is fine as long as the
content plays. Playback can only move backwards from the current playback position.
However, that is the cost of commencing playback quickly.
DEVELOPMENT
Git is the revision control system used by FFmpegfs. The complete repository is available here:
git clone https://github.com/nschlia/ffmpegfs.git
or the mirror:
git clone https://salsa.debian.org/nschlia/ffmpegfs.git
FFmpegfs is composed primarily of C++17 with a small amount of C. The following libraries are utilised:
• FUSE
FFmpeg home pages:
• FFmpeg
FILES
/usr/local/bin/ffmpegfs, /etc/fstab
AUTHORS
This fork with FFmpeg support has been maintained by Norbert Schlia since 2017 to date.
Based on work by K. Henriksson (from 2008 to 2017) and the original author, David Collett (from 2006 to
2008).
Much thanks to them for the original work and giving me a good head start!
LICENSE
This program can be distributed under the terms of the GNU GPL version 3 or later. It can be found online
or in the COPYING file.
This file and other documentation files can be distributed under the terms of the GNU Free Documentation
License 1.3 or later. It can be found online or in the COPYING.DOC file.
FFMPEG LICENSE
FFmpeg is licensed under the GNU Lesser General Public License (LGPL) version 2.1 or later. However,
FFmpeg incorporates several optional parts and optimizations that are covered by the GNU General Public
License (GPL) version 2 or later. If those parts get used the GPL applies to all of FFmpeg.
See https://www.ffmpeg.org/legal.html for details.
COPYRIGHT
This fork with FFmpeg support copyright (C) 2017-2024 Norbert Schlia.
Based on work copyright (C) 2006-2008 David Collett, 2008-2013 K. Henriksson.
Much thanks to them for the original work!
This is free software: you are free to change and redistribute it under the terms of the GNU General
Public License (GPL) version 3 or later.
This manual is copyright (C) 2010-2011 K. Henriksson and (C) 2017-2024 by N. Schlia and may be
distributed under the GNU Free Documentation License (GFDL) 1.3 or later with no invariant sections, or
alternatively under the GNU General Public License (GPL) version 3 or later.
ffmpegfs 2.15 Januar 2024 FFMPEGFS(1)