media_play

media_play(STRING* name,BMAP* target, var volume)

media_loop(STRING* name,BMAP* target, var volume)

Plays a movie or audio stream from a file to the screen or to a texture or panel. media_play plays the stream once, media_loop repeats it until it is explicitly stopped. As many movie, sound or music files as supported by the hardware can be played simultaneously - for instance, to play two midi files at the same time you'd normally need two sound cards. All file formats supported by installed CODECs can be played with this instruction - .avi, .mpg, .divx, .wmv, .wma, .wav, .mid, .mp3, .ogg and so on, even some still image formats like .bmp or .jpg.

Parameters:

name	Name of the multimedia file. !! The file is streamed from hard disk; therefore it must exist in the work folder, and won't be found in the path, in a buffer, or in a resource. Playing from a subfolder is only possible when adding the folder name, f.i. media_loop("media\\scene.avi", NULL, 100);.
target	C Pointer to a bmap that serves as target texture for the video stream, or NULL for playing the video in the whole engine window. Using a target texture, the video can be played on a model or sprite surface in the level.
volume	Individual audio volume of the stream, 0 ..100. The master volume for all streams is controlled by the midi_vol variable

Returns:

Handle of the multimedia stream, or 0 if the stream couldn't be played.

Speed:

Medium

Remarks:

Windows comes with default CODECs for several basic video formats, such as MPEG-2, WMV, or uncompressed AVI files. CODECs for other video or audio formats files are freely available on the internet. A general CODEC collection for almost all formats can be download at http://sourceforge.net/projects/ffdshow and used under the GPL license. For streaming .ogg files, an installer for Ogg Vorbis DirectShow filters (oggds0995.exe) is included in the external folder. The Ogg Vorbis filter was created by Tobias Waldvogel (http://tobias.everwicked.com ) and can be freely used and distributed for private and commercial purposes.
Many video format versions use the same file extension, so the extension alone (such as .avi or .mpg) does not tell you whether a video will play on your PC or not. For testing whether a CODEC for that format is installed on your PC, run a one-line script that just plays a video of the required type:
function main() { media_play("filename.ext",NULL,100); }
License restrictions apply to some file formats, like MP3 or DivX . Check required license fees before including such files in your game.
Keep movies as small as possible. The media_play instructions use the Microsoft CBaseVideoRenderer filter. If a movie has a higher resolution or frame rate than the PC can decode in real time, frames will be dropped, possibly resulting in low frame rates, flickering, and loss of synchronisation between video and sound. If the movie has no audio, or the volume is set at 0, loss of synchronisation is preferred over dropping frames, i.e. the movie runs in slight 'slow motion'.
Movies are played in true color (24 bit) mode, therefore use 24 bit movies if possible. High color movies (16 bit) are also supported, but play slower and look worse due to the color conversion process.
C The target bitmap for video streams can also be displayed with transparency or overlay flags. Normally the bitmap should have the same size as the video; for scaling the video, play it on a scaled PANEL. The bmap should be a 24 bit texture (such as from a .tga image) without alpha channel. Compressed textures or alpha channel textures can't receive video streams. On mipmapped textures, only the first mipmap receives the video stream - for seeing it from a distance, use a non-mippmapped texture or assign a material that switches mipmapping off for that object.
Movies play as separate tasks in the background while the normal functions continue. Use the media_playing() function for determining when a movie is finished. Some media types, like .bmp or .jpg still images, play endlessly and must explicitely be stopped by media_stop(). In some Windows versions, still images are not streamed at all, depending on the configuration - so we do not recommend to use this instruction for still images.
Two movies can not be played simultaneously onto the same bitmap.
Multimedia files have to be loaded from virtual memory before playing, so there can be a few milliseconds delay at the beginning or every loop repetition, depending on the hardware and the filter software. For avoiding this audible delay on audio files, use snd_loop for looping music in .wav or .ogg format.
Movies require a DirectX device for playing , and thus can't play in the first frame before the DirectX device is opened.

Example:

// Play music "ribanna.mid" at 50% volume endlessly.
mhandle = media_loop("ribanna.mid",NULL,50);
// Play movie "news.avi" on the tv_model entity with maximum volume
media_play("news.avi",bmap_for_entity(tv_model,0),100); 
// Play movie "news.mpg" on the full screen with maximum volume
media_play("news.mpg",NULL,100);