totem-video-thumbnailer

totem-video-thumbnailer [OPTIONS] INPUT_FILE OUTPUT_FILE

-s SIZE, --size=SIZE
    Specifies the maximum dimension (width or height) of the generated thumbnail in pixels. The aspect ratio is typically preserved, and the image will be scaled to fit within this size.

-t TIME, --time=TIME
    Sets the time, in seconds, from the beginning of the video where the frame should be captured for the thumbnail. For example, a value of '10' would capture a frame 10 seconds into the video.

-a, --aspect-correction
    Ensures the thumbnail maintains the video's original aspect ratio. If the specified size does not match the video's aspect, black bars (letterboxing or pillarboxing) will be added to fill the space.

-o FILE, --output-file=FILE
    Specifies the path for the output thumbnail image file. This option is often redundant if the output file is provided as the second positional argument on the command line.

-h, --help
    Displays a brief help message, showing available options and usage examples, then exits.

-v, --version
    Shows the version information of the totem-video-thumbnailer utility and exits.

totem-video-thumbnailer is a utility program designed to create static image thumbnails from video files. It's primarily used by desktop environments, such as GNOME's Nautilus file manager, to display visual previews of video content without opening the full player. The command takes an input video file, seeks to a specified time, captures a frame, and then scales it to a desired size before saving it as an output image file (commonly JPEG). It leverages the GStreamer multimedia framework for its decoding capabilities, supporting a wide range of video formats. This tool automates the process of generating rich visual cues for video collections, making it easier for users to identify and manage their video content at a glance without launching a full media player.

This command relies heavily on a properly configured GStreamer installation with all necessary video decoder plugins. Without the correct plugins for a given video format, thumbnail generation may fail or produce a blank image. It is typically invoked by desktop environments in the background via the XDG Thumbnailing Specification and is not commonly used directly by end-users for manual thumbnail creation. Performance can vary based on video complexity, resolution, and system hardware, potentially consuming significant CPU resources for high-resolution video processing.

While it's a command-line tool, totem-video-thumbnailer is primarily designed to be called by desktop environments or file managers (like Nautilus) for automatic thumbnail generation. It's part of the standard XDG Thumbnailing Specification, meaning it's invoked by a system-wide mechanism to create thumbnails on demand when a file manager requests them, rather than being a tool frequently executed manually by users.

totem-video-thumbnailer has been an integral part of the GNOME desktop environment's multimedia capabilities since the early 2000s, evolving alongside the Totem video player (now GNOME Videos). Its development has consistently aimed to improve user experience by providing quick visual access to video content within file managers, reducing the need to open full video players just for previewing. It serves as a backend component conforming to the `Shared MIME-info` database's thumbnail specifications and the XDG Thumbnailing Specification.

ffmpeg(1), vlc(1), mplayer(1), gstreamer(1)