is an Open Source project for creating visual timelines:

Cool, what's this?

Visual timelines show you the structure of a video at a glance, by visualizing its color development. Try hovering over/tapping on the image!

First, they're pretty!

And second, they are useful: When you integrate them into actual video players, you can use them for navigation! With a little practise, you can differentiate scenes, and skip to parts that interest you. In a talk recording, you can see when the slides change, or where the Q&A begins. We think this makes video navigation more efficient, precise, and active.

What's the status?

As of 2018, Timelens is under active development. We're building an efficient command line tool, which you can use to generate visual timelines yourself. See below on how to install and how to use it.

We're also going to build an easy-to-use JavaScript plugin for web-based video players, including really good documentation! Finally, we plan to integrate Timelens into, the video archive of the Chaos Computer Club.

How can I keep in touch?

The simplest way is to subscribe to our newsletter! You'll be the first to receive news about the project, probably a few times a month:

Also, you can follow us on Twitter, if that's your thing: @timelens_io

Who's behind this?

The Timelens project (formerly known as nordlicht) was started by Sebastian Morr, a computer scientist, programmer, and designer from Germany. He's enthusiastic about free licenses, food, and minimalism, and he values autonomy, creativity, and curiosity. He has attended a scientific workshop on Origami in the Caribbean, backpacked through Japan, and is drawing algorithm assembly instructions.

When he stumbled over the moviebarcode Tumblr in 2011, he immediately wanted two things: An efficient tool for generating these "visual timelines" himself. And a really good integration into video players, so they could be used for navigation!

Now, supported by the Prototype Fund, he can make that vision a reality!


Can I see more examples?

Sure! Try clicking around in the visual timelines below the videos! Click the video itself to pause it:


If you're using Arch Linux, you can install the Timelens command line tool from the AUR, using your AUR helper of choice, e.g.

$ yaourt -S timelens-git

For other platforms, there are no packages or binaries yet (let me know if you want to help change that). But you can build Timelens yourself, here's how:


Timelens is written in the Rust programming language, so you'll need a working Rust installation. On Unix-based systems, you'll probably want to run these commands to install rustup and cargo (which are like pip or npm, but for Rust):

$ curl -f >
$ sh
$ source ~/.cargo/env

There's also a single dependency: The multimedia framework GStreamer. To install the required components for your platform, follow these instructions.

You can then compile Timelens like this:

$ git clone
$ cd timelens
$ cargo build --release

This will create the binary target/release/timelens, which you can use like this:

$ ./target/release/timelens video.mp4


The most basic usage is to simply give Timelens the name of a video file. Timelens will create a visual timeline from the video, using a default size of 1000x100 pixels, and the default filename INPUT_FILE.timeline.jpg.

$ timelens video.mp4

You can override the filename and the timeline's size explicitly:

$ timelens video.mp4 --timeline timeline.jpg -w 1000 -h 500

The second thing Timelens can do is creating thumbnail grids. To keep the individual files small, Timelens will often split the thumbnails into several files. It will also create a text file in the VTT format, which references the thumbnails' positions.

Use the --thumbnails option to specify the name of the VTT file:

$ timelens video.mp4 --thumbnails thumbnails.vtt

For each thumbnail, the file specifies a time range and a filename, as well as the X/Y position in that file and its width and height, in the Media Fragment syntax:


00:00.000 --> 00:05.786

00:05.786 --> 00:11.572

00:11.572 --> 00:17.358


Timelens will also create one or more JPEG files containing the thumbnails, which are referenced from the VTT file. Here's the first one:


You can look at the complete documentation with the --help option, or simply by specifying no arguments:

$ timelens
timelens 0.1.0
Sebastian Morr <>

Timelens creates visual timelines from video files, which visualize
the videos' color development and can be integrated into video players.
That way, users can navigate videos more precisely and actively.

Additionally, Timelens can create thumbnail grids, which can be used
to display preview images when the user hovers over the visual timeline.
Timelens can output a VTT file, which references the thumbnails' positions.

Project homepage:

    timelens <INPUT_FILE>

            Name of the input video file.

    -w, --width <NUM>
            Width of the visual timeline in pixels [default: height*10, or 1000, if height
            is unspecified].
    -h, --height <NUM>
            Height of the visual timeline in pixels [default: width/10].

        --timeline <JPEG_FILE>
            Create a visual timeline from the input file, which visualizes its color
            development. The result will be written to the specified file in JPEG format
            [default, if neither `--timeline` nor `--thumbnails` is used:
        --thumbnails <VTT_FILE>
            Extract thumbnails from the input file, in the form of one or several thumbnail
            grids. A VTT file referencing the thumbnails' positions will be written to the
            specified location. The number of thumbnails corresponds to the `--width`
            option, because the thumbnails are meant to be used together with the visual
    -H, --thumbnail-height <NUM>
            Height of the individual thumbnails in the thumbnail grids. Their width is
            derived from the video's aspect ratio [default height: 90].
            Print help information.

            Print version information.

    timelens video.mp4 
            Generate a visual timeline called 'video.mp4.timeline.jpg' of default size.
    timelens video.mp4 --timeline timeline.jpg -w 1000 -h 500
            Override size and name of the timeline file.
    timelens video.mp4 --thumbnails thumbnails.vtt
            Generate thumbnail grids and a corresponding VTT file referencing their locations.