Introduction

iTorque 2D supports the following multimedia formats:

• MP3 - Stream audio files

• MP4 and M4V - Movie formats

The functions to play these media formats are exposed to TorqueScript. Before you can call the following functions, you must enable the features using the iOS settings in the iTorque 2D Editor. These settings are located in the iDevice Feature Builder section under the Project Tab:

Streaming MP3s

There is only one way to load and play an mp3 in iTorque 2D. A single function is responsible for streaming:

// filePath - A string containing file path and name of the mp3
// loopin - If true, loop the audio continuously. If false, just play it once
// streamHandle - Returned by function, stores a reference to the current stream
streamHandle = startiPhoneAudioStream(string filePath, bool looping);

In the above code, the return value is mentioned. It is a good idea to use a global variable for storing the stream's handle. You can have multiple stream running, but you will want to stop them at some point. To stop an audio stream, you will call the following function:

// streamHandle - Reference to the audio stream you want to stop
stopiPhoneAudioStream(streamHandle);

The following example code assumes a MP3 file named "rain.mp3" exists in the projectFiles/game/data/audio folder. If you want to play a looping mp3 from the start of the level until the level ends, start by opening projectFiles/game/scripts/game.cs. You would then add the following code to the bottom of the startGame(%level) function:

In game.cs, startGame function

if($platform $= "iphone")
{
   // Removes the default cursor when deployed to an iOS device
   hideCursor();

   // Store the file path globally, in case it needs to be used later
   $musicStreamFile = "game/data/audio/rain.mp3";

   // Start streaming (playing) the rain.mp3 audio file
   $musicStreamHandle = startiPhoneAudioStream($musicStreamFile, true);
}

As mentioned earlier, you need to stop the audio stream at some point to avoid memory leaks or crashing. For this example, the rain audio will play as long as the level is loaded. The best place to stop the audio stream is right before the level is unloaded. In the same game.cs script, find the endGame() function. Add the following code to the top of this function:

Note: The last three lines of this function already exist.

function endGame()
{
   // If the game is running on iOS
   if($platform $= "iphone")
   {
      // Stop the audio stream created earlier
      stopiPhoneAudioStream($musicStreamHandle);
   }
   
   sceneWindow2D.endLevel();
   moveMap.pop();
   moveMap.delete();
}

Playing Movies

Movie playback functionality is defined in the following two source files in the engine/source/platformiPhone directory:

• iPhoneMoviePlayback.h

• iPhoneMoviePlayback.mm

You can play a movie from TorqueScript using the playiPhoneMovie function:

// %filename - Name and path to the movie file
// %filetype - Movie format (currently only support MP4 and M4V
// %scalemode - The scaling mode to use when playing a movie
// %controlstyle - The style of the playback controls
// Returns true if the file was found, false otherwise
playiPhoneMovie(%filename, %filetype, %scaleode, %controltyle);

A common practice is to create a folder in projectFiles/game/data called movies. If you have movie in that folder called "MyMovie.mp4", the following code shows the proper way to play it:

// First parameter is the path and name for MyMovie
// mp4 is the file type
// scalemode will be set to MPMovieScalingModeNone
// controlstyle will be set to MPMovieControlStyleNone
playiPhoneMovie("game/data/MyMovie", "mp4", 0, 0);

You can read a full reference for the MPMoviePlayerController class in the iOS Dev Center. The reference docs will help you extend the movie player if you need additional functionality. It also covers how MPMovieScalingMode and MPMovieControlStyle affect playback.