GSTFS-NG(8)

NAME
gstfs-ng - Next Generation Gstreamer Filesystem

SYNOPSIS
gstfs-ng [-o option[,...]] BASEDIRECTORY MOUNTPOINT
mount -t gstfs-ng [-o option[,...]] BASEDIRECTORY MOUNTPOINT

DESCRIPTION
gstfs-ng is a read-only filesystem that acts as a gstreamer-based transcoding facade (visible at MOUNTPOINT) over an existing BASEDIRECTORY tree.

Perhaps gstfs-ng is best explained by an example use case:

A music archive stored on a computer might enjoy ample space for disk storage and, therefore, the archive maintainer might choose a high quality lossless encoding to store content. For lack of storage, however, the same archive might not fit on a portable media player. A portable media player might require a lower quality lossy encoding to store the complete archive.

In order to balance the needs between quality and size, one might be tempted to store both a high quality lossless and a low quality lossy archive on their computer. This, of course, requires additional storage on the computer and presents the archive maintainer with synchronization problems.

gstfs-ng helps by allowing one archive type appear as another. In this case, it allows the large high quality archive to appear as a smaller low quality one. To make this happen, gstfs-ng must be told where the base of the original archive is, where the transcoded archive should appear and the transcodings that should take place between them.

The transcodings that are to occur are specified as transcode mappings. Each mapping must specify a source extension (e.g. source=flac), a target extension (e.g. target=ogg) and a gstreamer pipeline description that can be used to perform the transcoding. gstfs-ng can perform many such mappings at once as long as the source to target file name extension mapping is one-to-one. gstfs-ng creates a new transcode mapping as soon as it has all three components and then prepares to build the next.

While gstfs-ng relies on fuse (Filesystem in Userspace) technology to allow transcoded files to appear as a filesystem, it relies on gstreamer technology to actually perform the transcodings. This means that that type of transcodings that gstfs-ng can perform are only limited by the capabilities of (audio/video/tagging formats supported by) the installed gstreamer implementation.

gstfs-ng is dependent on gstreamer-1.0 interfaces as of gstfs-ng version 1.0.

OPTIONS
Options are delimited by commas. Commas embedded in option values must be escaped with a preceding backslash. Below is a summary of each mount option that gstfs-ng accepts.

source=SOURCE
    Set the source file extention in a transcode mapping. All files with this SOURCE extension under the BASEDIRECTORY will appear under the gstfs-ng filesystem as transcoded files with the TARGET file extension.

target=TARGET
    Set the target file extention in a transcode mapping. TARGET and SOURCE can be the same value. One might do this with a PIPELINE that changes the quality or size of an encoding. For example, a PIPELINE that takes source jpeg files and scales them to target jpeg files (see below).

pipeline=PIPELINE
    PIPELINE is a gstreamer parseable pipeline description. These descriptions typically contain whitespace that might need to escaped from a shell/interpreter. Properties of gstreamer elements must be surrounded by whitespace. Spaces in fstab fields must be represented as \040 (octal for ASCII space). Commas embedded in a gstfs-ng pipeline option value must be escaped with a preceding backslash. For testing, one might specify an empty pipeline for an identity transcoding. A transcoding pipeline that converts a flac audio encoding to ogg/vorbis might be specified as follows:

    flacparse ! flacdec ! audioconvert ! vorbisenc ! oggmux

    A transcoding pipeline that converts ogg/vorbis to mp3 might be specified as follows:

    oggdemux ! vorbisdec ! audioconvert ! lamemp3enc ! id3v2mux

    A transcoding pipeline that scales jpeg images to a specified width and height might be specified as follows (as a pipeline option value to gstfs-ng, the commas will have to be escaped with preceding backslashes):

    jpegdec ! videoscale ! video/x-raw,width=300,height=300 ! jpegenc

    Use gst-inspect to inspect the properties available for gstreamer elements. For testing, use the gst-launch utility.

cacheCount=COUNT
    Limit the number of transcoded images that gstfs-ng will cache in memory after transcoding them. COUNT should be specified as a number of images but may also have a single character suffix to suggest scale (k, m or g to multiply by 2 **10, **20 or **30, respectively). The default is 50 images.

cacheMemory=MEMORY
    Limit the total size of transcoded images that gstfs-ng will cache in memory after transcoding them. MEMORY should be specified as a number of bytes but may also have a single character suffix to suggest scale (k, m or g to multiply by 2 **10, **20 or **30, respectively). Alternately, a number with a % suffix is interpreted as a percentage of physical memory. The default is 25% of physical memory.

cacheTime=TIME
    Limit the time that transcoded images will be cached in memory by gstfs-ng after transcoding them. TIME should be specified as a number of seconds but may also have a single character suffix to suggest scale (m, h, d, w, y to multiply by one minute, hour, day, week, year). The default is 1 hour.

cachePersist=PERSIST
    Specify a directory where cached images will persist after they are removed from memory. This persistant cache will last between gstfs-ng sessions so that transcoding need not be redone. Cached files in the PERSIST directory are named using stat -c %d.%i.%Y reported identifiers from the referencing source file. Note that the reference will not break if the source file is moved or renamed but will if it is modified (as it should be). At the beginning of a gstfs-ng session, the PERSIST directory will be purged of unreferenced images.

trueSize
    When the size of a file that has yet to be transcoded is requested, this option requests that the transcoding be performed and allowed to complete so that the true size of the file can be reported. The default is to report 0 or, if transcoding is in progress, the size of the transcoding so far.

readAhead=READAHEAD
    As files to be transcoded are "touched" by attribute requests or directory listings, start the transcoding operation in the background. READAHEAD limits the number of such operations that can be happening concurrently. The default is 16. To be effective, READAHEAD should be tuned along with cache COUNT, MEMORY, TIME and PERSIST settings so that the images generated by read ahead operations are in the image cache when needed.

EXAMPLES
Mount /source on /target using an identity gstreamer pipeline to transcode flac to flac files:

    gstfs-ng -o source=flac,target=flac,pipeline= /source /target

or

    mount -t gstfs-ng -o source=flac,target=flac,pipeline= /source /target

/etc/fstab entry for the above:

    /source /target gstfs-ng source=flac,target=flac,pipeline= 0 0

Unmount /target:

    fusermount -u /target

The above example is useless except to illustrate the base form for all usage. That is, it specifies a minimal transcode mapping operation in the form required by gstfs-ng. It is simple to grow this example, however, by supplying a non-empty PIPELINE and specifying SOURCE and TARGET appropriately. Multiple such mappings can be added as long as the mapping is one-to-one. For mounts via /etc/fstab or the mount command, gstfs-ng must be installed as /sbin/mount.gstfs-ng as this is where mount will go to mount filesystems of this type. Normally, FUSE based file systems such as this will dynamically allocate inode numbers for files and the inode number of a file may change over the lifetime of the mount even though the source file does not change. If the source directory is limited to a single file system, one can add the use_ino FUSE option to use the inode number of source files for associated files in the target. This should be done for the sake of NFS clients of NFS exported FUSE file systems to avoid stale NFS file handles. To synchronize the /target directory with a like-named directory under a a FAT file system mounted at, say, /media/thumb/, the following rsync command might be used:

    rsync -av --modify-window=1 --delete /target /media/thumb/

ACKNOWLEDGEMENT
Ross Tyler thanks Bob Copeland whose original concept and implementation inspired this one.

SEE ALSO
gst-inspect gst-launch