Movie Support

Movie support is implemented using SMPEG.

Scrupp only supports MPEG-1 videos! Furthermore automatic aspect ratio correction is not implemented. For example, a video file has a resolution of 352x240 (= 1.47:1) but the aspect ratio is defined by the header as 1.34:1. Therefore the video has to be resized in order to correct the aspect ratio. A resolution of 352x262 satisfies the ratio. The scale factor in vertical direction calculates to 262/240 = 1.09.

How to create MPEG-1 movies

The recommended way to convert video files to the MPEG-1 format is using MEncoder, a command line program which is a part of MPlayer. It is available for all major platforms.

I got good results with the following command:

mencoder -oac lavc -ovc lavc \
  -of mpeg -mpegopts format=mpeg1 \
  -vf harddup -srate 44100 -af lavcresample=44100 \
  -lavcopts vcodec=mpeg1video:acodec=mp2 -ofps 25 -mc 0 -noskip \
  -o output.mpeg movie.file

Loading

scrupp.addMovie(filename): Loads the MPEG-1 movie file with the given filename. Returns a movie object.

Methods

movie:play([loop])

Starts the movie playback. If the movie has an audio channel, music playback is paused and the audio of the movie is played back using the music channel. The optional boolean parameter loop enables (=true) or disables (=false, default) looping of the movie. Remember to call movie:render() in the render callback function!

movie:pause()

Pauses the movie playback.

movie:resume()

Resumes the movie playback.

movie:rewind()

Rewinds the movie.

movie:stop()

Stops the movie and gives the music channel free. After that, music can be played back again. Music that has been paused by the movie playback will be resumed.

movie:getWidth()

Returns the width of the movie.

movie:getHeight()

Returns the height of the movie.

movie:getSize()

Returns the width and the height of the movie.

movie:getInfo()

Returns a table containing information about the movie. This is the structure of the returned table:

table = {
	hasAudio          = boolean,
	hasVideo          = boolean,
	currentFrame      = integer,
	currentFPS        = number,  -- frames per second
	audioString       = string,  -- e.g. "MPEG-1 Layer 2 128kbit/s 44100Hz stereo"
	currentAudioFrame = integer,
	currentOffset     = integer,
	totalSize         = integer, -- filesize in bytes
	currentTime       = number,  -- in seconds
	totalTime         = number   -- in seconds
}

movie:isPlaying()

Returns true if the movie is playing, false otherwise.

movie:setAlpha(alpha)

Changes the alpha value of the movie. alpha has to be between 0 (transparent) and 255 (opaque).

movie:getAlpha()

Returns the current alpha value of the movie. This value is between 0 (transparent) and 255 (opaque).

movie:loadFirstFrame()

Loads the first frame of the movie. Note: This function does not display anything on the screen. It just updates the internal image that is rendered during the next call to movie:render()

movie:render(x,y)

Renders the movie at the window coordinates x and y.

movie:render(table)

This is nearly the same as the last one. This time a table contains the arguments. This function is the same as image:render(table) but renders the current movie frame, not an image. The complete structure of the table follows.

table = {
	x, -- x-coordinate of the movie frame position -- mandatory
	y, -- y-coordinate of the movie frame position -- mandatory
	centerX = [x-coordinate of the center for positioning, scaling and rotation], -- optional
	centerY = [y-coordinate of the center for positioning, scaling and rotation], -- optional
	scaleX = [scale factor for the x-axis], -- optional
	scaleY = [scale factor for the y-axis], -- optional
	rotate = [angle in degrees to rotate the movie frame], -- optional
	rect = { x, y, width, height }, -- optional
	color = { red, green, blue, alpha } -- optional
}

The first two elements of the array part of the table have to be the x- and y-coordinate of the point that the movie frame should be rendered at. The table may have an optional rect entry. This has to be a table describing the rectangle the movie frame should be clipped to. It contains the x- and y-coordinate of the upper left corner and the width and height of the rectangle inside the movie frame. The entries centerX and centerY are optional and default to zero, the left-upper corner of the movie frame. scaleX and scaleY are optional as well and default to one. rotate has a default value of zero dregrees and is optional, too. The optional color entry is a table defining some kind of color filter. If you have a grayscale movie, it will be colorized with this color. As always the table looks like this: {red, green, blue, [alpha]} with each value between 0 and 255. The default is opaque white, so the color of the movie frame is not changed.

movie:remove()

If the movie is playing, this function has the same effects as a call to movie:stop(). In addition, this function removes the movie from memory. After that, calling any method of the movie variable is forbidden and will raise an error.

Example

-- create a dummy window, because you have to call
-- scrupp.init() before you can load movies
scrupp.init("Movie Test", 10, 10, 32, false)

-- load a mpeg file
local movie = scrupp.addMovie("path_to_mpeg_file")

-- get the width and height of the movie
local width, height = movie:getSize()

-- resize the Scrupp window to the movie size
scrupp.init("Movie Test", width, height, 32, false)

-- play the movie in a loop
movie:play(true)

main = {
	render = function(dt)
		movie:render(0,0)
	end,
	
	keypressed = function(k)
		if k == "ESCAPE" then scrupp.exit() end
	end,
}