'\" t
.\"     Title: ffmpegfs
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: Januar 2021
.\"    Manual: User Commands
.\"    Source: ffmpegfs 2.2
.\"  Language: English
.\"
.TH "FFMPEGFS" "1" "Januar 2021" "ffmpegfs 2\&.2" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ffmpegfs \- mounts and transcodes a multitude of formats to one of the target formats on the fly
.SH "SYNOPSIS"
.sp
\fBffmpegfs\fR [\fIOPTION\fR]\&... \fIIN_DIR\fR \fIOUT_DIR\fR
.SH "DESCRIPTION"
.sp
The ffmpegfs(1) command will mount the directory \fIIN_DIR\fR on \fIOUT_DIR\fR\&. Thereafter, accessing \fIOUT_DIR\fR will show the contents of \fIIN_DIR\fR, with all supported media files transparently renamed and transcoded to one of the supported target formats upon access\&.
.sp
Supported output formats:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MP4 (MPEG\-4)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
WebM
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
OGG
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MOV (QuickTime File Format)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Prores (a MOV container for Apple Prores video & PCM audio)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Opus (audio only)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MP3 (MPEG\-2 Audio Layer III)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
WAV (Waveform Audio File Format)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
AIFF (Audio Interchange File Format)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ALAC (Apple Lossless Audio Codec)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
JPG (video to frameset)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
PNG (video to frameset)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
BMP (video to frameset)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
TS (MPEG transport stream)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
HLS (HTTP Live Streaming)
.RE
.SH "OPTIONS"
.sp
Usage: ffmpegfs [OPTION]\&... IN_DIR OUT_DIR
.sp
Mount IN_DIR on OUT_DIR, converting audio/video files upon access\&.
.SS "Encoding options"
.PP
\fB\-\-desttype\fR=TYPE, \fB\-odesttype\fR=TYPE
.RS 4
Select destination format\&.
\fITYPE\fR
can currently be:
.sp
\fBMP4\fR,
\fBMP3\fR,
\fBOGG\fR,
\fBWEBM\fR,
\fBMOV\fR,
\fBPRORES\fR,
\fBAIFF\fR,
\fBALAC\fR,
\fBOPUS\fR,
\fBWAV\fR,
\fBJPG\fR,
\fBPNG\fR,
\fBBMP\fR,
\fBTS\fR
or
\fBHLS\fR\&.
.sp
To stream videos,
\fBMP4\fR,
\fBOGG\fR,
\fBWEBM\fR
or
\fBMOV\fR/\fBPRORES\fR
must be selected\&.
.sp
To use HTTP Live Streaming, set
\fBHLS\fR\&.
.sp
When a destination
\fBJPG\fR,
\fBPNG\fR
or
\fBBMP\fR
is chosen, all frames of a video source file will be presented in a virtual directory named after the source file\&. Audio will no be available\&.
.sp
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\&.
.sp
Default:
\fBmp4\fR
.RE
.PP
\fB\-\-autocopy\fR=OPTION, \fB\-oautocopy\fR=OPTION
.RS 4
Select auto copy option,
\fIOPTION\fR
can be:
.TS
allbox tab(:);
lt lt
lt lt
lt lt
lt lt
lt lt.
T{
\fBOFF\fR
T}:T{
Never copy streams, transcode always\&.
T}
T{
\fBMATCH\fR
T}:T{
Copy stream if target supports codec\&.
T}
T{
\fBMATCHLIMIT\fR
T}:T{
Same as MATCH, only copy if target not larger, transcode otherwise\&.
T}
T{
\fBSTRICT\fR
T}:T{
Copy stream if codec matches desired target, transcode otherwise\&.
T}
T{
\fBSTRICTLIMIT\fR
T}:T{
Same as STRICT, only copy if target not larger, transcode otherwise\&.
T}
.TE
.sp 1
This can speed up transcoding significantly as copying streams uses much less computing power as compared to transcoding\&.
.sp
\fBMATCH\fR
copies a stream if the target supports it, e\&.g\&. an AAC audio stream will be copied to MPEG although FFmpeg\(cqs target format is MP3 for this container\&. H264 would be copied to ProRes although the result will be a regular MOV/MP4, not a ProRes file\&.
.sp
\fBSTRICT\fR
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\&.
.sp
Default:
\fBOFF\fR
.RE
.PP
\fB\-\-recodesame\fR=OPTION, \fB\-orecodesame\fR=OPTION
.RS 4
Select recode to same format option,
\fIOPTION\fR
can be:
.TS
allbox tab(:);
lt lt
lt lt.
T{
\fBNO\fR
T}:T{
Never recode to same format\&.
T}
T{
\fBYES\fR
T}:T{
Always recode to same format\&.
T}
.TE
.sp 1
Default:
\fBNO\fR
.RE
.PP
\fB\-\-profile\fR=NAME, \fB\-oprofile\fR=NAME
.RS 4
Set profile for target audience,
\fINAME\fR
can be:
.TS
allbox tab(:);
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt.
T{
\fBNONE\fR
T}:T{
no profile
T}
T{
\fBFF\fR
T}:T{
optimise for Firefox
T}
T{
\fBEDGE\fR
T}:T{
optimise for MS Edge and Internet Explorer > 11
T}
T{
\fBIE\fR
T}:T{
optimise for MS Edge and Internet Explorer ⇐ 11
T}
T{
\fBCHROME\fR
T}:T{
Google Chrome
T}
T{
\fBSAFARI\fR
T}:T{
Apple Safari
T}
T{
\fBOPERA\fR
T}:T{
Opera
T}
T{
\fBMAXTHON\fR
T}:T{
Maxthon
T}
.TE
.sp 1
\fBNote:\fR
Applies to MP4 output format only, ignored for all other formats\&.
.sp
Default:
\fBNONE\fR
.RE
.PP
\-\-\fBlevel\fR=NAME, \-o \fBlevel\fR=NAME
.RS 4
Set level for output if available,
\fINAME\fR
can be:
.TS
allbox tab(:);
lt lt
lt lt
lt lt
lt lt.
T{
\fBPROXY\fR
T}:T{
Proxy \(en apco
T}
T{
\fBLT\fR
T}:T{
LT \(en apcs
T}
T{
\fBSTANDARD\fR
T}:T{
standard \(en apcn
T}
T{
\fBHQ\fR
T}:T{
HQ \- apch
T}
.TE
.sp 1
\fBNote:\fR
Applies to MP4 output format only, ignored for all other formats\&.
.sp
Default:
\fBHQ\fR
.RE
.SS "Audio Options"
.PP
\fB\-\-audiobitrate\fR=BITRATE, \fB\-o audiobitrate\fR=BITRATE
.RS 4
Audio encoding bitrate\&.
.sp
Default:
\fB128 kbit\fR
.sp
\fBAcceptable values for \fR\fB\fIBITRATE\fR\fR\fB:\fR
.sp
\fBmp4:\fR
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\&.
.sp
\fBmp3:\fR
For sampling frequencies of 32, 44\&.1, and 48 kHz,
\fIBITRATE\fR
can be among 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, and 320 kbps\&.
.sp
For sampling frequencies of 16, 22\&.05, and 24 kHz,
\fIBITRATE\fR
can be among 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, and 160 kbps\&.
.sp
When in doubt, it is recommended to choose a bitrate among 96, 112, 128, 160, 192, 224, 256, and 320 kbps\&.
.sp
\fBBITRATE\fR
can be defined as\&... * n bit/s: # or #bps * n kbit/s: #K or #Kbps * n Mbit/s: #M or #Mbps
.RE
.PP
\fB\-\-audiosamplerate\fR=SAMPLERATE, \fB\-o audiosamplerate\fR=SAMPLERATE
.RS 4
Limits the output sample rate to
\fISAMPLERATE\fR\&. If the source file sample rate is more it will be downsampled automatically\&.
.sp
Typical values are 8000, 11025, 22050, 44100, 48000, 96000, 192000\&.
.sp
If the target codec does not support the selected sample rate, the next matching rate will be chosen (e\&.g\&. if 24K is selected ut only 22\&.05 or 44\&.1 KHz supported, 22\&.05 KHz will be set)\&.
.sp
Set to 0 to keep source rate\&.
.sp
Default:
\fB44\&.1 kHz\fR
.sp
\fBSAMPLERATE\fR
can be defined as\&... * In Hz: # or #Hz * In kHz: #K or #KHz
.RE
.PP
\fB\-\-audiochannels\fR=CHANNELS, \fB\-o audiochannels\fR=CHANNELS
.RS 4
Limits the number of output channels to
\fICHANNELS\fR\&. If the source has more channels, the number will be reduced to this limit\&.
.sp
Typical values are 1, 2 or 6 (e\&.g\&. 5\&.1) channels\&.
.sp
If the target codec does not support the selected number of channels, transcoding may fail\&.
.sp
Set to 0 to keep the number of channels\&.
.sp
Default:
\fB2 channels (stereo)\fR
.RE
.SS "Video Options"
.PP
\fB\-\-videobitrate\fR=BITRATE, \fB\-o videobitrate\fR=BITRATE
.RS 4
Video encoding bit rate\&. Setting this too high or low may cause transcoding to fail\&.
.sp
Default:
\fB2 Mbit\fR
.sp
\fBmp4:\fR
May be specified as 500 to 25000 kbit\&.
.sp
\fBBITRATE\fR
can be defined as\&... * n bit/s: # or #bps * n kbit/s: #K or #Kbps * n Mbit/s: #M or #Mbps
.RE
.PP
\fB\-\-videoheight\fR=HEIGHT, \-o \fBvideoheight\fR=HEIGHT
.RS 4
Sets the height of the transcoded video\&.
.sp
When the video is rescaled the aspect ratio is preserved if \-\-width is not set at the same time\&.
.sp
Default:
\fBkeep source video height\fR
.RE
.PP
\fB\-\-videowidth\fR=WIDTH, \-o \fBvideowidth\fR=WIDTH
.RS 4
Sets the width of the transcoded video\&.
.sp
When the video is rescaled the aspect ratio is preserved if \-\-height is not set at the same time\&.
.sp
Default:
\fBkeep source video width\fR
.RE
.PP
\fB\-\-deinterlace\fR, \-o \fBdeinterlace\fR
.RS 4
Deinterlace video if necessary while transcoding\&.
.sp
May need higher bit rate, but will increase picture quality when streaming via HTML5\&.
.sp
Default:
\fBno deinterlace\fR
.RE
.SS "HLS Options"
.PP
\fB\-\-segment_duration\fR, \-o \fBsegment_duration\fR
.RS 4
Set duration of one video segment of HLS stream\&. This argument is a floating point value, e\&.g can be set to 2\&.5 for 2500 milliseconds\&.
.sp
Should normally be left at default\&.
.sp
\fBNote:\fR
Applies to HLS output format only, ignored for all other formats\&.
.sp
Default:
\fB10 seconds\fR
.RE
.SS "Album Arts"
.PP
\-\-\fBnoalbumarts\fR, \-o \fBnoalbumarts\fR
.RS 4
Do not copy album arts into output file\&.
.sp
This will reduce the file size, may be useful when streaming via HTML5 when album arts are not used anyway\&.
.sp
Default:
\fBadd album arts\fR
.RE
.SS "Virtual Script"
.PP
\-\-\fBenablescript\fR, \-o \fBenablescript\fR
.RS 4
Add virtual index\&.php to every directory\&. It reads scripts/videotag\&.php from the FFmpegfs binary directory\&.
.sp
This can be very handy to test video playback\&. Of course, feel free to replace videotag\&.php with your own script\&.
.sp
Default:
\fBDo not generate script file\fR
.RE
.PP
\-\-\fBscriptfile\fR, \-o \fBscriptfile\fR
.RS 4
Set the name of the virtual script created in each directory\&.
.sp
Default:
\fBindex\&.php\fR
.RE
.PP
\-\-\fBscriptsource\fR, \-o \fBscriptsource\fR
.RS 4
Take a different source file\&.
.sp
Default:
\fBscripts/videotag\&.php\fR
.RE
.SS "Cache Options"
.PP
\fB\-\-expiry_time\fR=TIME, \fB\-o expiry_time\fR=TIME
.RS 4
Cache entries expire after
\fITIME\fR
and will be deleted to save disk space\&.
.sp
Default:
\fB1 week\fR
.RE
.PP
\fB\-\-max_inactive_suspend\fR=TIME, \fB\-o max_inactive_suspend\fR=TIME
.RS 4
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\&.
.sp
Default:
\fB15 seconds\fR
.RE
.PP
\fB\-\-max_inactive_abort\fR=TIME, \fB\-o max_inactive_abort\fR=TIME
.RS 4
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\&.
.sp
Default:
\fB30 seconds\fR
.RE
.PP
\fB\-\-prebuffer_size\fR=SIZE, \fB\-o prebuffer_size\fR=SIZE
.RS 4
Files will be decoded until the buffer contains this much bytes allowing playback to start smoothly without lags\&.
.sp
Set to 0 to disable pre\-buffering\&.
.sp
Default:
\fB100 KB\fR
.RE
.PP
\fB\-\-max_cache_size\fR=SIZE, \fB\-o max_cache_size\fR=SIZE
.RS 4
Set the maximum diskspace used by the cache\&. If the cache would grow beyond this limit when a file is transcoded, old entries will be deleted to keep the cache within the size limit\&.
.sp
Default:
\fBunlimited\fR
.RE
.PP
\fB\-\-min_diskspace\fR=SIZE, \fB\-o min_diskspace\fR=SIZE
.RS 4
Set the required diskspace on the cachepath mount\&. If the remaining space would fall below
\fISIZE\fR
when a file is transcoded, old entries will be deleted to keep the diskspace within the limit\&.
.sp
Default:
\fB0 (no minimum space)\fR
.RE
.PP
\fB\-\-cachepath\fR=DIR, \fB\-o cachepath\fR=DIR
.RS 4
Sets the disk cache directory to
\fIDIR\fR\&. Will be created if not existing\&. The user running FFmpegfs must have write access to the location\&.
.sp
.RE
.PP
\fB\-\-disable_cache\fR, \-o \fBdisable_cache\fR
.RS 4
Disable the cache functionality completely\&.
.sp
Default:
\fBenabled\fR
.RE
.PP
\fB\-\-cache_maintenance\fR=TIME, \fB\-o cache_maintenance\fR=TIME
.RS 4
Starts cache maintenance in
\fITIME\fR
intervals\&. This will enforce the expery_time, max_cache_size and min_diskspace settings\&. Do not set too low as this can slow down transcoding\&.
.sp
Only one FFmpegfs process will do the maintenance by becoming the master\&. If that process exits, another will take over so that always one will do the maintenance\&.
.sp
Default:
\fB1 hour\fR
.RE
.PP
\fB\-\-prune_cache\fR
.RS 4
Prune cache immediately according to the above settings at application start up\&.
.RE
.PP
\fB\-\-clear_cache\fR, \fB\-o clear_cache\fR
.RS 4
Clear cache on start up\&. All previously transcoded files will be deleted\&.
.sp
\fBTIME\fR
can be defined as\&... * Seconds: # * Minutes: #m * Hours: #h * Days: #d * Weeks: #w
.sp
\fBSIZE\fR
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
.RE
.SS "Other"
.PP
\fB\-\-max_threads\fR=COUNT, \fB\-o max_threads\fR=COUNT
.RS 4
Limit concurrent transcoder threads\&. Set to 0 for unlimited threads\&. Recommended values are up to 16 times number of CPU cores\&. Should be left at default\&.
.sp
Default:
\fB16 times number of detected cpu cores\fR
.RE
.PP
\fB\-\-decoding_errors\fR, \fB\-o decoding_errors\fR
.RS 4
Decoding errors are normally ignored, leaving bloopers and hiccups in encoded audio or video but yet creating a valid file\&. When this option is set, transcoding will stop with an error\&.
.sp
Default:
\fBIgnore errors\fR
.RE
.PP
\fB\-\-min_dvd_chapter_duration\fR=SECONDS, \fB\-o min_dvd_chapter_duration\fR=SECONDS
.RS 4
Ignores DVD chapters shorter than SECONDS\&. Set to 0 to disable\&. This avoids transcoding errors for DVD chapters too short to detect its streams\&.
.sp
Default:
\fB1 second\fR
.RE
.PP
\fB\-\-win_smb_fix\fR, \fB\-o win_smb_fix\fR
.RS 4
Windows seems to access the files on Samba drives starting at the last 64K segment simply when the file is opened\&. Setting \-\-win_smb_fix=1 will ignore these attempts (not decode the file up to this point)\&.
.sp
Default:
\fBon\fR
.RE
.SS "Logging"
.PP
\fB\-\-log_maxlevel\fR=LEVEL, \fB\-o log_maxlevel\fR=LEVEL
.RS 4
Maximum level of messages to log, either ERROR, WARNING, INFO, DEBUG or TRACE\&. Defaults to INFO, and always set to DEBUG in debug mode\&.
.sp
Note that the other log flags must also be set to enable logging\&.
.RE
.PP
\fB\-\-log_stderr\fR, \fB\-o log_stderr\fR
.RS 4
Enable outputting logging messages to stderr\&. Automatically enabled in debug mode\&.
.RE
.PP
\fB\-\-log_syslog\fR, \fB\-o log_syslog\fR
.RS 4
Enable outputting logging messages to syslog\&.
.RE
.PP
\fB\-\-logfile\fR=FILE, \fB\-o logfile\fR=FILE
.RS 4
File to output log messages to\&. By default, no file will be written\&.
.RE
.SS "General/FUSE options"
.PP
\fB\-d\fR, \fB\-o debug\fR
.RS 4
Enable debug output\&. This will result in a large quantity of diagnostic information being printed to stderr as the program runs\&. It implies
\fB\-f\fR\&.
.RE
.PP
\fB\-f\fR
.RS 4
Run in foreground instead of detaching from the terminal\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print usage information\&.
.RE
.PP
\fB\-V\fR, \fB\-\-version\fR
.RS 4
Output version information\&.
.RE
.PP
\fB\-c\fR, \fB\-\-capabilities\fR
.RS 4
Output FFmpeg capabilities: list on the system available codecs\&.
.RE
.PP
\fB\-s\fR
.RS 4
Force single\-threaded operation\&.
.RE
.SH "USAGE"
.sp
Mount your filesystem like this:
.sp
.if n \{\
.RS 4
.\}
.nf
ffmpegfs [\-\-audiobitrate bitrate] [\-\-videobitrate bitrate] musicdir mountpoint [\-o fuse_options]
.fi
.if n \{\
.RE
.\}
.sp
For example,
.sp
.if n \{\
.RS 4
.\}
.nf
ffmpegfs \-\-audiobitrate 256K \-videobitrate 2000000 /mnt/music /mnt/ffmpegfs \-o allow_other,ro
.fi
.if n \{\
.RE
.\}
.sp
In recent versions of FUSE and FFmpegfs, the same can be achieved with the following entry in /etc/fstab:
.sp
.if n \{\
.RS 4
.\}
.nf
ffmpegfs#/mnt/music /mnt/ffmpegfs fuse allow_other,ro,audiobitrate=256K,videobitrate=2000000 0 0
.fi
.if n \{\
.RE
.\}
.sp
Another (more modern) form of this command:
.sp
.if n \{\
.RS 4
.\}
.nf
/mnt/music /mnt/ffmpegfs fuse\&.ffmpegfs allow_other,ro,audiobitrate=256K,videobitrate=2000000 0 0
.fi
.if n \{\
.RE
.\}
.sp
At this point files like /mnt/music/{empty}*\&.flac and /mnt/music/{empty}*\&.ogg will show up as /mnt/ffmpegfs/{empty}*\&.mp4\&.
.sp
Note that the "allow_other" option by default can only be used by root\&. You must either run FFmpegfs as root or better add a "user_allow_other" key to /etc/fuse\&.conf\&.
.sp
"allow_other" is required to permit any user access to the mount, by default this is only possible for the user who launched FFmpegfs\&.
.SH "HOW IT WORKS"
.sp
When a file is opened, the decoder and encoder are initialised and the file metadata is read\&. At this time the final filesize can be determined approximately\&. This works well for MP3, AIFF or WAV output files, but only fair to good for MP4 or WebM because the actual size heavily depends on the content encoded\&.
.sp
As the file is read, it is transcoded into an internal per\-file buffer\&. This buffer continues to grow while the file is being read until the whole file is transcoded in memory\&. Once decoded the file is kept in a disk buffer and can be accessed very fast\&.
.sp
Transcoding is done in an extra thread, so if other processes should access the same file they will share the same transcoded data, saving CPU time\&. If all processes close the file before its end, transcoding will continue for some time\&. If the file is accessed again before timeout, transcoding will continue, if not it stops and the chunk created so far discarded to save disk space\&.
.sp
Seeking within a file will cause the file to be transcoded up to the seek point (if not already done)\&. This is not usually a problem since most programs will read a file from start to finish\&. Future enhancements may provide true random seeking (but if this is feasible is yet unclear due to restrictions to positioning inside compressed streams)\&.
.sp
MP3: ID3 version 2\&.4 and 1\&.1 tags are created from the comments in the source file\&. They are located at the start and end of the file respectively\&.
.sp
MP4: Same applies to meta atoms in MP4 containers\&.
.sp
MP3 target only: A special optimisation is made so that applications which scan for id3v1 tags do not have to wait for the whole file to be transcoded before reading the tag\&. This dramatically speeds up such applications\&.
.sp
WAV: A pro format WAV header will be created with estimates of the WAV file size\&. This header will be replaced when the file is finished\&. It does not seem necessary, though, as most modern players obviously ignore this information and play the file anyway\&.
.SH "ABOUT OUTPUT FORMATS"
.sp
A few words to the supported output formats\&. There is not much to say about the MP3 output as these are regular constant bitrate (CBR) MP3 files with no strings attached\&. They should play well in any modern player\&.
.sp
MP4 files are special, though, as regular MP4s are not quite suited for live streaming\&. Reason being that the start block of an MP4 contains a field with the size of the compressed data section\&. Suffice to say that this field cannot be filled in until the size is known, which means compression must be completed first, a file seek done to the beginning, and the size atom updated\&.
.sp
For a continuous live stream, that size will never be known\&. For our transcoded files one would have to wait for the whole file to be recoded to get that value\&. If that was not enough some important pieces of information are located at the end of the file, including meta tags with artist, album, etc\&. Also, there is only one big data block, a fact that hampers random seek inside the contents without having the complete data section\&.
.sp
Subsequently many applications will go to the end of an MP4 to read important information before going back to the head of the file and start playing\&. This will break the whole transcode\-on\-demand idea of FFmpegfs\&.
.sp
To get around the restriction several extensions have been developed, one of which is called "faststart" that relocates the aforementioned meta data from the end to the beginning of the MP4\&. Additionally, the size field can be left empty (0)\&. isml (smooth live streaming) is another extension\&.
.sp
For direct to stream transcoding several new features in MP4 need to be active (ISMV, faststart, separate_moof/empty_moov to name them) which are not implemented in older versions of FFmpeg (or if available, not working properly)\&.
.sp
By default faststart files will be created with an empty size field so that the file can be started to be written out at once instead of encoding it as a whole before this is possible\&. Encoding it completely would mean it would take some time before playback can start\&.
.sp
The data part is divided into chunks of about 1 second length, each with its own header, thus it is possible to fill in the size fields early enough\&.
.sp
As a draw back not all players support the format, or play it with strange side effects\&. VLC plays the file, but updates the time display every few seconds only\&. When streamed over HTML5 video tags, sometimes there will be no total time shown, but that is OK, as long as the file plays\&. Playback cannot be positioned past the current playback position, only backwards\&.
.sp
But that\(cqs the price of starting playback fast\&.
.SH "DEVELOPMENT"
.sp
FFmpegfs uses Git for revision control\&. You can obtain the full repository with:
.sp
.if n \{\
.RS 4
.\}
.nf
git clone https://github\&.com/nschlia/ffmpegfs\&.git
.fi
.if n \{\
.RE
.\}
.sp
FFmpegfs is written in a little bit of C and mostly C++11\&. It uses the following libraries:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
FUSE
.RE
.sp
FFmpeg home pages:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
FFmpeg
.RE
.SH "FUTURE PLANS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Create a windows version
.RE
.SH "FILES"
.sp
\fB/usr/local/bin/ffmpegfs\fR, \fB/etc/fstab\fR
.SH "AUTHORS"
.sp
This fork with FFmpeg support is maintained by Norbert Schlia since 2017\&.
.sp
Based on work by K\&. Henriksson (from 2008 to 2017) and the original author David Collett (from 2006 to 2008)\&.
.sp
Much thanks to them for the original work!
.SH "LICENSE"
.sp
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\&.
.sp
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\&.
.SH "FFMPEG LICENSE"
.sp
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\&.
.sp
See https://www\&.ffmpeg\&.org/legal\&.html for details\&.
.SH "COPYRIGHT"
.sp
This fork with FFmpeg support copyright (C) 2017\-2021 Norbert Schlia\&.
.sp
Based on work copyright (C) 2006\-2008 David Collett, 2008\-2013 K\&. Henriksson\&.
.sp
Much thanks to them for the original work!
.sp
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\&.
.sp
This manual is copyright (C) 2010\-2011 K\&. Henriksson and (C) 2017\-2021 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\&.