Convert Apple QTVR Files Using FFmpeg

Apple QuickTime Virtual Reality (QTVR) is a legacy interactive format that packs panoramic images or multi-angle object views inside a standard QuickTime container (.mov). While modern media players can no longer render the interactive interface, FFmpeg allows you to decode the embedded visual data and convert it into standard modern formats such as MP4 videos or individual PNG image sequences.

1. Inspect the File Streams

QTVR files often contain multiple tracks, including custom metadata, navigation tracks, and the underlying video or image sequence. Run the following command to identify the correct visual stream:

ffmpeg -i input.mov

Examine the output under Stream mapping or Stream #0:x. Look for the stream labeled Video (typically encoded in Cinepak, Sorenson, JPEG, or uncompressed formats). Note its stream index, which is commonly 0:v:0.

2. Convert to a Standard MP4 Video

If the QTVR is an "Object Movie" (a rotating object filmed across several frames) or a video panorama, you can transcode the raw track into a universal H.264 video:

ffmpeg -i input.mov -map 0:v:0 -c:v libx264 -pix_fmt yuv420p output.mp4
  • -map 0:v:0 ensures FFmpeg targets only the primary video stream, ignoring incompatible navigation or metadata tracks.
  • -c:v libx264 encodes the stream into H.264.
  • -pix_fmt yuv420p converts legacy color spaces to standard YUV 4:2:0 for playback compatibility across modern browsers and devices.

3. Extract Frames as an Image Sequence

For panoramic QTVR files (cylindrical or cubic) or object nodes that you intend to restitch into modern 360-degree viewers or WebGL environments, extracting the raw image frames is ideal:

ffmpeg -i input.mov -map 0:v:0 -vsync 0 frame_%04d.png
  • -vsync 0 prevents FFmpeg from dropping or duplicating frames, ensuring every distinct angle or panorama tile is preserved.
  • frame_%04d.png exports the frames sequentially as lossless PNG files.

4. Handling Cylindrical Panoramas

Many QTVR panoramas are single-frame, wide-aspect-ratio cylindrical strips. If FFmpeg extracts only a single very wide image (e.g., 2048x768), you have obtained the complete panoramic canvas. You can import this image directly into modern equirectangular conversion tools or viewer libraries like Three.js or Pannellum.