Creating a Dome Master from a MOV or MP4 file

Creating a Dome Master from a MOV or MP4 file

Or, one possible answer to the question: “What’s a fast way to fill a hard drive?”


Ken Scott
Digital Chaotics LLC

Mac/Linux script contributed by
Sascha Kriegel
Planetarium Hamburg


In this post I’ll show you how to create a dome master from a MOV or MP4 file. It’s pretty straightforward once you know the steps. If you’re in a hurry, you can skip past the explanation and go directly to the Summary, below ».

All of the video files for sale here (DomeSavers », DomeLoops », and DomeArts ») are delivered in the MP4 standard video file format. The files contain both the images and audio needed to play your movies. The files can be played with most video player software. However, a video player (the computer running it, actually) can have trouble keeping up with the demand of producing 30 or more fulldome frames per second. The video player has to read the data for each frame from the file, then decompress it into an image for viewing by humans, and then copy that image to the screen. Keep in mind that individual fulldome frames can be rather large. An uncompressed 4K x 4K fulldome frame is 50MB of data. That’s just one frame. At 30 frames per second, that means the video player has to process 1.5GB per second to keep up.

Believe me, that’s hard work. That kind of workload can easily saturate even a high-end gaming PC, resulting in jerky, blocky, and/or severely smeared playback. The hardest parts are reading the file from disk and the decompression of each frame. Putting the files on an internal solid state drive (SSD) » will definitely improve the speed of reading the data, but that won’t improve times for the heavier step: the decompression. It’s pretty hefty math, and for videos containing complex or dynamic images (e.g., my animations) it’s simply impossible for an average laptop to keep up. Fortunately, there’s a way around that. The trick is to decompress the images ahead of time, taking that step out of the “real-time” path. Once they’re decompressed into individual image files – a dome master – the player then simply reads in the images and displays them. Much easier.

There’s a free tool called FFMPEG that can convert your video into a series of image files. FFMPEG is the de facto industry standard for reading and writing nearly all video file formats. In fact, it’s very likely that FFMPEG code is running behind the scenes of your favorite desktop video tools – both open source and high-end commercial products. There are two very good reasons for that:

  • it really is the best thing out there
  • it’s free

I use FFMPEG. So can you.

FFMPEG » can be downloaded for free here:

Download it, install it, and ensure that it’s in your PATH. (google:  “add to path Windows” »  “add to path Mac” »  “add to path Linux” ») You are now all-powerful, at least where video conversion is concerned.

FFMPEG is a command line tool. Unlike most apps, you can’t just double-click it. You have to use the command line to make it run. It’s not hard. Don’t be afraid. It’ll be okay. I promise. If you follow these instructions, then it’s extremely unlikely that you’ll damage anything. 99.999% of the time it’ll work just fine, and even then the worst that can go wrong is that you’ll run out of disk space. Yes, I’m saying that the resulting directory full of image files will be REALLY BIG. For 4K fulldome movies, figure 20GB per minute of video on average, and double that isn’t unheard of. If you run out of disk space, Don’t Panic ». Just delete the “master” folder that the script created (more on that in a minute) and empty the trash. Then get bigger hard drive », and try again.

Once you have FFMPEG installed, run the script below. Be sure to choose the correct script type. For Windows it’s the ‘.cmd’ version. For Mac and Linux it’s the ‘.sh’ version. Copy the correct script into a file on your system. On Windows, it should be a “.cmd” file – I named mine “movie2master.cmd”, and it’s in stored “C:\Transcoders””. For Mac and Linux, it should be a “.sh” file (e.g., “movie2master.sh”) and you’ll need to mark that file as executable (“sudo chmod 555 movie2master.sh”). In any case, you’ll probably want to add the location of the new file to your system PATH (or use the workaround I’ll describe later).

To run the script, open a command-line window (google: “open a command-line window”), and type:

Windows:  movie2master src-file dst-type dst-prefix
Mac/Linux:  movie2master.sh src-file dst-type dst-prefix

where…

  • src-file is the path to the video file you want to convert (usually a MOV, MP4, MPG, or MPEG file)
  • dst-type is the type of image frame files you want – either “JPG” or “PNG”
  • dst-prefix is the prefix you want on each file, e.g., “FRAME” or “IMG” (something not too long)

Once everything is running correctly you’ll see a whole bunch of incomprehensible programmer-ish-type scroll by, and then it will settle down, telling you what frame it’s generating. When it’s all done, the script will exit back to the command line. It’ll take a while. Be patient. For each minute of the source video, the script takes about 10 minutes to generate all of the frames. (Your mileage may vary.)

Note to Windows users:  if you accidentally click in the command-line window while the script is running, and you see a block cursor somewhere in the screen (that is, not the little blinking one at the bottom of the window), then the program is paused. It’s frozen. It will just sit there until you clear it out. Fortunately, it’s easy to fix. To unpause it, bring that window to the front, and hit the ENTER key.  Voilà!  It’s running again. You’ll see the last line start ticking upwards again, and the block cursor won’t be visible anymore.

Once the script has finished you should have a “master” directory sitting in the directory where you ran the script.  That directory will contain two sub-directories:  “video” and “audio”.  The “video” directory will have a bunch of files named something like “FRAME_######.PNG”, with the #’s indicating the order of the frames.  If the input video file has and audio track, then the “audio” directory will contain several audio files whose names will be self-apparent.  (If the input video file doesn’t have an audio track, then the “audio” directory will be empty.)

That workaround I mentioned earlier is pretty simple.  If you don’t want to add a directory to your PATH, then simply change the command-line example above to include the entire path to your script, e.g.:

Windows:  C:\MyDrive\NewScript\movie2master myfile.mov PNG FRAME
Mac/Linux:  /usr/foo/ffmpegscripts/movie2master.sh myfile.mov PNG FRAME

The script generates a new “master” directory in the current working directory ». It deletes any previous “master” directory it finds there, along with all of its contents.

Summary

  1. Make sure you have plenty of disk space – a minimum of 30GB per minute of 4K fulldome video (maybe more, depending on the video content)
  2. Install the version of FFMPEG needed for your machine (http://ffmpeg.org), and make sure it’s in your system PATH
  3. Copy the script below into a file called “movie2master.cmd” (Windows) or “movie2master.sh” (Mac/Linux), and ensure that the file is also in your PATH
  4. Copy your source video file (MP4) into a directory by itself
  5. Open a command window, and move to the target directory you just created
  6. Execute the script:  
    • Windows: movie2master your_target_file.mp4 PNG FRAME
    • Mac/Linux: movie2master.sh your_target_file.mp4 PNG FRAME
  7. Wait for the script to complete (approx. 10-20 minutes for every 1 minute of video)
  8. Look for a “master” directory in the target directory, with sub-directories
    • “video”: holds image files labeled FRAME_000001.PNG, FRAME_000002.PNG, etc.
    • “audio”: holds WAV and MP3 audio files (but only if the source MP4 file had an audio track)

Best Practices

  • Put each source video file into a separate directory, and then run the command from that directory.  That way you’ll end up with a “master” directory sitting next to the original video file, and you’ll always know what it contains
  • You can never have too much hard disk space
  • Your computer will never be fast enough

Quick note (Windows): if you make the mistake of double-clicking on the script file, then you’ll see a command-line window flash on the screen very briefly. What happened is this: double-clicking on a icon causes your computer to try to execute the command. Double-clicking doesn’t give it the parameters it needs, so it runs without doing anything. Nothing bad happened. It just didn’t work. But it’s better if you don’t do that.


“movie2master” Script:

For Windows

REM movie2master.cmd
REM
REM Converts a MOV or MP4 file to an image sequence + audio files.
REM
REM Should work with most popular video file formats, but only MOV and MP4 have been tested.
REM
REM Creates a ‘master’ directory in the current working directory, and inside the ‘master’
REM directory it creates ‘video’ and ‘audio’ directories below that.
REM
REM If there’s no audio in the source file, then the ‘audio’ directory will be empty.
REM
REM ex: movie2master my_source_movie.MOV PNG FRAME
REM produces a series of PNG files prefixed with FRAME
REM
REM ex: movie2master my_source_mpeg.MP4 JPG FRM
REM produces a series of JPG files prefixed with FRM

set srcFile=%1
set dstSuffix=%2
set dstPrefix=%3

@echo Creating Dome Master for %srcFile
%if exist master (
@echo Deleting existing Dome Master
rd /s /q master
)
@echo Creating ‘master’ folder
md master
cd master
@echo Creating ‘audio’ folder
md audio
@echo Creating ‘video’ folder
md video
cd ..

@echo Writing Stereo WAV
start /B ffmpeg -i %srcFile% -vn -ac 2 -ar 44100 -f wav master/audio/STEREO.wav@echo Writing Stereo MP3
start /B ffmpeg -i %srcFile% -vn -ac 2 -ar 44100 -ab 320k -f mp3 master/audio/STEREO.mp3

@echo Writing Mono WAV
start /B ffmpeg -i %srcFile% -vn -ac 1 -ar 44100 -f wav master/audio/MONO.wav

@echo Writing Mono MP3
start /B ffmpeg -i %srcFile% -vn -ac 1 -ar 44100 -ab 320k -f mp3 master/audio/MONO.mp3

@echo Writing Left/Right WAVs
start /B ffmpeg -i %srcFile% -vn -ar 44100 -map_channel 0.0.0 master/audio/LEFT.wav -map_channel 0.0.1 master/audio/RIGHT.wav

@echo Writing Left/Right MP3s
start /B ffmpeg -i %srcFile% -vn -ar 44100 -ab 320k -map_channel 0.0.0 master/audio/LEFT.mp3 -ab 320k -map_channel 0.0.1 master/audio/RIGHT.mp3

@echo Writing Image Sequence
start /B /WAIT ffmpeg -i %srcFile% -r 30 master/video/%dstPrefix%_%%06d.%dstSuffix%

:end

For Mac & Linux

#!/bin/sh
# movie2master.sh
#
# Many thanks to Sascha Kriegel for this version!
#
# Converts a MOV or MP4 file to an image sequence + audio files.
#
# Should work with most popular video file formats, but only MOV and MP4 have been tested.
#
# Creates a ‘master’ directory in the current working directory, and inside the ‘master’
# directory it creates ‘video’ and ‘audio’ directories below that.
#
# If there’s no audio in the source file, then the ‘audio’ directory will be empty.
#
# example: movie2master.sh my_source_movie.MOV PNG FRAME
# …produces a series of PNG files prefixed with FRAME
#
# example: movie2master.sh my_source_mpeg.MP4 JPG FRM
# …produces a series of JPG files prefixed with FRM
#
#####
# NOTE: Be sure to make this file executable (e.g., ‘sudo chmod 555 video2master.sh’), or
# your shell may refuse to run this script
#####

export srcFile=$1
export dstSuffix=$2
export dstPrefix=$3

echo “Creating DomeMaster for “$srcFile
rm -Rf ./master

echo “Creating master folder”
mkdir master
cd master

echo “Creating audio folder”
mkdir audio

echo “Creating video folder”
mkdir video

cd ..

echo “Writing Stereo WAV”
ffmpeg -i $srcFile -vn -ac 1 -ar 44100 -f wav ./master/audio/MONO.wav

echo “Writing Left/Right WAVs”
ffmpeg -i $srcFile -vn -ar 44100 -map_channel 0.0.0 ./master/audio/LEFT.wav -map_channel 0.0.1 ./master/audio/RIGHT.wav

echo “Writing Left/Right MP3s”
ffmpeg -i $srcFile -vn -ar 44100 -ab 320k -map_channel 0.0.0 ./master/audio/LEFT.mp3 -ab 320k -map_channel 0.0.1 ./master/audio/RIGHT.mp3

echo “Writing Image Sequence”
echo “srcFile is $1, dstSuffix is $2, dstPrefix is $3.”
ffmpeg -i $srcFile -r 30 ./master/video/”$dstPrefix”_%06d.$dstSuffix

Please feel free to send suggestions for improvements on scripts and/or the instructions on their use. If you run into any problems at all, or something’s unclear, then please send me a note [ken.scott at digitalchaotics dot com].