What is a "hypervideo"?

A hypervideo is an interactive video format that enables hyperlinked, non-linear navigation between video fragments. With FrameTrail, we aim to create a hypervideo environment that provides a filmic answer to functional intertextuality — think of a World-Wide-Web where all the interconnected text fragments are replaced by film.

Read more on the History and Definition of the hypervideo concept.

Why "FrameTrail"?

"Frames" are the most basic components of film (moving images). A "Trail" is in this context the path these frames take when composed to a film sequence (a "trail of single frames" if you wish). The term stems from Vannevar Bushs groundbreaking essay "As We May Think" (1945) and his description of associative trails in the "memex" concept (which laid the foundation for all future hypertext systems, including the World-Wide-Web).
By choosing this name, we want to pay tribute to the original hypertext ideas (which contained many great concepts from which only the simplest made it into the WWW) and set the longterm goal to re-invent some of them for film-based hypermedia.

What are the different deployment modes?

FrameTrail supports three deployment modes — see the Installation guide for the full comparison table:

• Server mode — requires PHP 7.4+. Supports all features: persistent saves, multi-user accounts, media transcoding (with FFmpeg), and thumbnail generation.
• Local Folder mode — requires Chrome or Edge. No PHP or server needed. Data is saved directly to a folder on your computer.
• In-memory mode — works in any modern browser. No persistent saves (export via Save As).

The Setup Wizard shows a permission error — what do I do?

The Setup Wizard checks that FrameTrail can write to its own directory and the _data/ folder. If it reports a permission error, make the directory writable by the web server:

chmod -R 755 /path/to/frametrail

On shared hosting, you may need to set this via your hosting control panel or contact your provider.

Why does Local Folder mode require Chrome or Edge?

Local Folder mode uses the File System Access API to read and write files directly on your computer. This API is currently only supported by Chromium-based browsers (Chrome and Edge). Firefox does not support it. If you need Firefox support, use Server mode instead.

Why does [...] not work?

FrameTrail has been developed as a simple tool requiring only little knowledge and effort to set up and extend. On the contrary, you as a user have to take care of web-ready data formats and a suitable technical environment (i.e. small images, correctly encoded video files and a modern browser). If you think you did everything right and still experience problems, please inform us of bugs or any other issues you have.

Why is everything so slow?

You most likely added many webpage resources. While there is generally no limit, please keep in mind that every webpage you add as annotation or overlay needs to be fully loaded in the browser. So if you add 30 webpage resources to your hypervideo, this is similar to opening 30 websites at once in one browser window.
Some websites need more browser performance than others. Under extreme circumstances, a single website can be enough to crash the entire application. As we obviously don't have control over external webpages, just check if it get's better when you remove certain webpage resources from the hypervideo.

Does video upload require a specific format?

It depends on which deployment mode you are using:

• Server mode with FFmpeg: FrameTrail transcodes uploaded videos automatically on the server, so you can upload most common formats (MP4, MOV, AVI, MKV, etc.).
• Local Folder or In-memory mode: The browser plays the file directly — no transcoding happens. Use MP4 with H.264 encoding for the broadest browser compatibility. Recommended settings: 720p, 25 fps, ~3 Mbit/s bitrate.

What images can I upload?

You can use files with the ending: "jpg", "jpeg", "gif" and "png". Keep file sizes small for smooth playback — images should generally be under 500 KB.

What subtitle formats can I use?

For the subtitles, you have to use files in the "WebVTT" (.vtt) format. You can convert existing SRT files using FFmpeg:
ffmpeg -i input.srt output.vtt

Or use an online converter if you prefer a graphical tool.

Where can I upload [Word (.docx), PowerPoint (.pptx), etc.] files?

FrameTrail is a web application. This means you can only work with files which are "web-ready" / can be displayed in a browser. Please stick with the formats offered within the upload interface.

Why can I not login?

Did you login with the right credentials, but a warning message says: "User is not active. Please contact an admin!"?
This means that you have successfully been registered, but a security setting requires that your account is activated by an administrator before you can actually login.

What happens when I "fork" a Hypervideo?

Hypervideos are managed by their authors, thus a normal user can only "annotate" them but cannot change Overlays or Video Links. By forking a hypervideo, you create a copy for yourself that you completely own and are fully able to edit. As a reference is still kept to the "origin", forking is more than just copying or cloning. The term stems from open source software development.

Can I export a Hypervideo / entire project?

Yes — use the built-in Save As feature to download hypervideos as JSON or ZIP, export a standalone HTML file, or simply copy the /_data folder to another FrameTrail instance. In server mode, a server-side ZIP export is also available. See the Managing Data tutorial for a complete walkthrough.

Is FFmpeg required, and how do I install it?

FFmpeg is optional but required for server-side video transcoding and thumbnail generation in server mode. Without it, FrameTrail still works — uploaded videos just need to be browser-compatible (MP4/H.264) and thumbnails will be generated client-side instead.

Check if FFmpeg is installed:
ffmpeg -version

Install FFmpeg:

• Debian / Ubuntu: sudo apt install ffmpeg
• macOS (Homebrew): brew install ffmpeg
• Windows: Download from ffmpeg.org/download.html and add it to your PATH.