Using Videos

From BlinkenSisters

This page in German. | Diese Seite auf Deutsch.

Using videos in BlinkenSisters is currently not very intuitive; we are working on better toolkits, but this may take some time.


Contents

[edit]

Supported Formats

  • OGG/Theora: We support playing OGG/Theora files in theory. But we're still working to integrate support on most operating system, so this support is for internal testing only at the moment, so using the format is currently NOT a topic of this documentation.
  • BMF/Video: The BMF (BlinkenSisters Meta File) supports a video mode. Generating and using this format is the topic of this dokumentation.


[edit]

The BMF Format


[edit]

Technical explanation

YOU SHOULD READ THIS TO UNDERSTAND THE WORKINGS OF THE BMF-TOOLS!

The BMF Format is internally a number of sequentially archived files or data "chunks".

For using BMF as a video format, a header with basic information (framerate, screen resolution) is stored as the first chunk.

Next comes the (optional) audio file, which is started the moment it is read into memory. All formats generally supported as audio formats by BlinkenSisters are allowed.

After that comes a series of image files (Supported: jpeg), that all must be the resolution described in the header. Currently, only 640x480 pixels is supported.

The last chunk is a special "END" chunk. When it is read, the player stops the audio if running and gives control back to the calling function.

Currently, only a fixed framerate is supported; it must be an integer number of at leat "1".

[edit]

How to compress a video

First you have to prepare a separate directory, containing all the jpeg-frames for your movie. The directory name MUST NOT contain spaces!

All images have to have a "number-name": First image is "0001.jpg", next is "0002.jpg", next is "0003.jpg". So all numbers must be padded with leading zeros; the number must be 4 digits long, no other characters allowed. The extension MUST be ".jpg".

To compress the video, you have to use the "bmfcompress" tool, its syntax is 

bmfcompress FPS NUM_OF_FRAMES OUTPUTFILE INPUTDIRECTORY SOUNDFILE
  • FPS: Frames per second, integer number of at least 1; shouldn't be more than 20, so the video will run smoothly on slower systems.
  • NUM_OF_FRAMES: Number of frames you want to compress to the movie, should be the same number as the last "number-name" without extension in the directory.
  • OUTPUTFILE: The filename for the BMF the tool should generate
  • INPUTDIRECTORY: Due to various reasons, bmfcompress shouldn't be called in the directory your images reside but in the parent directory. So this is the directory name you put your "number-name" files in.
  • This parameter is optional. The filename of the audiofile to be used. The audio-file must be in the same directory as the "number-name" files.

For example, if your directory layout is something like this (Where D is a directory, F a file): 

D MYADDON
D MYADDON/myvideo
F MYADDON/myvideo/0001.jpg
F MYADDON/myvideo/0002.jpg
F MYADDON/myvideo/0003.jpg
F MYADDON/myvideo/0004.jpg
(more "number-name" files)
F MYADDON/myvideo/0140.jpg
F MYADDON/myvideo/mysound.ogg

And you want a framerate of, say 10 Frames per second, you change to the directory MYADDON and call bmfcompress like this: 

cd MEINPFAD_ZU_ADDONS/MYADDON
bmfcompress 10 140 myvideo.bmf myvideo mysound.ogg

If you wanna compress a video without sound, just leave the last parameter: 

bmfcompress 10 140 myvideo.bmf myvideo


[edit]

Using videos in addons

There are a number of "default" videos the engine will look for. It it finds one of these, it will play them instead of displaying a static image:

  • livelost.bmf: Played if you loose a live.
  • levelwon.bmf: Something of a misnomer. It always plays when it loads a level, including the first one. The MZ_Moviepack uses it to display a "Get Ready" animation
  • gameover.bmf: If the player looses his/her last live without finishing the last level (a typical gameover situation...), this video is played.
  • gamewin.bmf: Is the player suceeds in playing through all levels with lives to spare (a typical gamewon situation...), this video is played.
  • startanim.bmf: This is somewhat special. This video is played during startup of the program as well as in the atraction mode (when the menu was idle for too long). For the official release, we won't accept anything that doesn't clearly display "MoveZIG Entertainment", though.

Of course, you can also play a video by LUA-Script anytime and as often if you want. See the scripting docs for details. The basic command is 

PlayVideo(filename, trackergui)
  • filename: The name of the bmf-file without path
  • trackergui: Usually 0 (zero), set it to 1 to have BlinkenSisters add a simple, green "Tracker" overlay as seen by some ancient video games.

So, for your video you may for example call: 

if myevent == user_switches_something then
    PlayVideo("myvideo.bmf", 0);
end
Retrieved from "http://www.blinkensisters.org/wiki/index.php/Using_Videos"