Multimedia functions

CDAudio

CDAudio (eCDAudioFunction, int param)

The PARAM parameter is used by some of the functions for various reasons; if it is not needed for the particular function you are calling, pass zero instead.

The tasks performed are as follows depending on the COMMAND parameter:

eCDIsDriverPresent - checks if there is a CD-ROM driver available on
   the system. Returns 1 if there is, and 0 if there is not.
eCDGetPlayingStatus - checks whether the CD drive is currently playing
   an audio track. Returns 1 if it is, and 0 if it is not.
eCDPlayTrack - starts playback from track PARAM on the CD. If the track
   does not exist, or if it is a data track, nothing happens.
eCDPausePlayback - pauses the currently playing audio track.
eCDResumePlayback - continues from where the track was paused.
eCDGetNumTracks - returns the number of tracks on the CD
   currently in the drive. If the drive is empty, returns 0.
eCDEject - ejects the drive tray if the drive has the ability. This is
   a feature you'll play with to start off because it's neat, and then
   realize that it has no real use in your game.
   Your script does not continue until the drive is fully ejected.
eCDCloseTray - the reverse of Eject. This will pull the drive tray back
   in again. Your script does not continue until the drive has been
   fully closed.
eCDGetCDDriveCount - returns the number of CD drives in the
   system, normally 1.
eCDSelectActiveCDDrive - changes the current CD drive to PARAM,
   where PARAM ranges from 1 to (number of CD drives). All the other
   CD Audio functions operate on the current CD drive.

Cross-Platform Support

Windows: Yes, but supports 1 CD-ROM drive only
MS-DOS: Yes, if CD-ROM device driver loaded
Linux: Yes, but supports 1 CD-ROM drive only

Example:

CDAudio(eCDPlayTrack, 3);

GetCurrentMusic

GetCurrentMusic()

Example:

if (GetCurrentMusic()==-1)
    PlayMusic(2);

See Also: IsMusicPlaying, IsSoundPlaying, SetMusicRepeat, SetMusicVolume

GetMIDIPosition

GetMIDIPosition ()

Example:

if(GetMIDIPosition()==50)
PlayMusic(2);

See Also: SeekMIDIPosition

GetMP3PosMillis

GetMP3PosMillis ()

If the current track is not an MP3 or OGG track, returns 0.

If the background music is currently crossfading between two tracks, this returns the position of the old track which is fading out.

Example:

if (GetMP3PosMillis() > 30000)
  SeekMP3PosMillis(0);

See Also: SeekMP3PosMillis

IsChannelPlaying

IsChannelPlaying (int channel)

NOTE: Be careful with this function for actions like looping sounds, since if the user doesn't have a sound card this will always return 0.

See the description of PlaySoundEx for more on sound channels.

Example:

if (IsChannelPlaying(3)==0)
  PlaySoundEx(20, 3);

See Also: IsSoundPlaying, PlaySoundEx

IsMusicPlaying

IsMusicPlaying ()

Example:

if(IsMusicPlaying()==0)
PlayMusic(3);

See Also: GetCurrentMusic

IsMusicVoxAvailable

IsMusicVoxAvailable()

Returns 1 if the MP3/OGG music files are available, 0 if not.

NOTE: This function ONLY deals with the MUSIC.VOX file. If you have bundled MP3 files seperately in the game directory, they will still be played by the game, but this function will not return 1 if they are there.

Example:

if (IsMusicVoxAvailable()==0)
    Display ("You don't have the music pack"); 

See Also: IsSpeechVoxAvailable

IsSoundPlaying

IsSoundPlaying ()

If the sound has finished, or none was played, returns 0.

NOTE: Be careful with this function for actions like looping sounds, since if the user doesn't have a sound card this will always return 0.

NOTE: This function does not report if background music or ambient sounds are playing.

Example:

if (IsSoundPlaying()==0)
  PlaySound(20);

See Also: GetCurrentMusic, IsChannelPlaying

IsSpeechVoxAvailable

IsSpeechVoxAvailable()

Returns 1 if the speech files are available, 0 if not.

Example:

if (IsSpeechVoxAvailable()==0)
    Display ("You don't have the voice pack"); 

NOTE: This function used to be called IsVoxAvailable, but has now been renamed to avoid confusion.

See Also: IsMusicVoxAvailable

PlayAmbientSound

PlayAmbientSound (int channel, int sound, int volume, int x, int y)

CHANNEL is the sound channel number. Currently this must always be 1, but in future multiple ambient sounds at once may be supported in which case you would be able to specify a different channel.

SOUND is the sound number, which identifies the file to load. The game will try to load SOUNDx.MP3 and SOUNDx.WAV, where X is the sound number you specify here.

VOLUME is the volume of the sound. This can be from 1 to 255, where 255 is the loudest. Generally you won't want to make this very loud since it's only supposed to be a background noise, such as a humming machine room or flowing water.

X and Y allow you to specify co-ordinates if you want a directional ambient sound. If you just pass X and Y as zero, the sound will be played at the specified volume throughout the room. However, if there is a certain spot in the room where the sound is emanating from, you can pass its co-ordinates here, and the sound will get louder as the player approaches that spot in the room. In this case, the VOLUME parameter specifies the maximum possible volume, when the player is standing right on the spot.

NOTE: The sound will stop when the player leaves the room.

NOTE: In order to optimise the looping of the sound, the entire sound effect is loaded into memory. Therefore, do not use this function to play normal background music with, since music files tend to be very large and are better streamed from disk with the normal music functions.

Example:

PlayAmbientSound (1, 10, 150, 250, 110);

See Also: PlayMusic, PlaySound, StopAmbientSound

PlayFlic

PlayFlic (int flic_number, int options)

OPTIONS has these meanings:

0  player can't skip animation
1  player can press ESC to skip animation
2  player can press any key or click mouse to skip animation
+10 (ie.10,11,12) do not stretch to full-screen, just play at flc size

Example:

PlayFlic (2,1);

See Also: PlayVideo

PlayMP3File

PlayMP3File (string filename)

Since normally MP3 files are built into the MUSIC.VOX file, there may be occasions where you want one MP3 (for example, the intro music) to be distributed with your main game rather than the music pack. So, this function allows you to play any named MP3 or OGG file. However, you will have to bundle the file seperately in your game distribution (it is not automatically compiled into the EXE).

Example:

PlayMP3File ("chesney.mp3");

See Also: PlayMusic, StopMusic

PlayMusic

PlayMusic (int music_number)

Example:

PlayMusic(2);

See Also: PlayMP3File, PlayMusicQueued, PlaySound, StopMusic

PlayMusicQueued

PlayMusicQueued (int music_number)

This command allows you to build up a playlist of music to be played, one after another. You can call this up to 10 times, to add up to 10 tracks to the playlist.

NOTE: This command uses the current setting of SetMusicRepeat to determine whether the queued track will repeat or not. You can only queue one track while SetMusicRepeat is on (since it will never finish, any further queued tracks would never play).

NOTE: The playlist is cancelled if you call PlayMusic (or use any other Play Music commands such as the Play Music On Room Load feature), or if you call StopMusic.

Example:

SetMusicRepeat(0);
PlayMusic(2);
PlayMusicQueued(3);
SetMusicRepeat(1);
PlayMusicQueued(4);

See Also: PlayMusic, SetMusicRepeat, StopMusic

PlaySilentMIDI

PlaySilentMIDI (int music_number)

This is a very specialised command and will not be needed by most games. It is designed to allow the beats of a MIDI file to be used for timing of game events and for other purposes.

The MIDI is silently played on the speech sound channel, so you cannot use this in a talkie game.

Example:

PlaySilentMIDI(2);

See Also: GetMIDIPosition, SeekMIDIPosition

PlaySound

PlaySound (int sound_number)

This command will find a free channel to play the sound on, if it can. Otherwise, it will silence any previously playing sounds and override them with the new sound.

Pass -1 as SOUND_NUMBER to stop any currently playing sounds.

This command returns the channel number that the new sound is playing on, or -1 if it did not play for any reason.

Example:

PlaySound(3);

See Also: PlayMusic, PlaySoundEx

PlaySoundEx

PlaySoundEx (int sound_number, int channel)

About sound channels

AGS now uses a multi-channel sound system. There are currently 6 sound channels, numbered from 0 to 5. They are used as follows:

0	Background music, used by PlayMusic
1	Ambient sounds, used by PlayAmbientSound
2	Voice speech, used when you have automatic speech in your game.
3-5	Free channels, used by PlaySound, view frame sounds and so on.

When you use a Play Sound command, AGS automatically chooses a free channel from 3-5 to play the sound on. This means you can have up to 3 simultaneous sound effects. If they are all in use and you want to play another sound, one of the previous sounds will be cut off.

With PlaySoundEx, you can elect to play a sound effect on a specific channel, from 3 to 5. This gives you greater control of the sound effects, should you need it.

You cannot play a sound on channels 0-2 using this function, because there are seperate ways of starting sound on those channels.

Example:

PlaySoundEx(3, 4);

See Also: IsChannelPlaying, PlaySound, SetChannelVolume, StopChannel

PlayVideo

PlayVideo (string filename, int skip, int flags)

FLAGS can be one of the following:

0: the video will be played at original size, with AVI audio
1: the video will be stretched to full screen, with appropriate
   black borders to maintain its aspect ratio and AVI audio.
10: original size, with game audio continuing (AVI audio muted)
11: stretched to full screen, with game audio continuing (AVI audio muted)

0  player can't skip video
1  player can press ESC to skip video
2  player can press any key to skip video
3  player can press any key or click mouse to skip

IMPORTANT: Any video files you have for this cannot be compiled into the main game data file, so you will have to place them seperately in the Compiled folder for them to work.

IMPORTANT: The end player will have to have the correct codecs installed in order to play the video. Bear in mind that if you encode your intro with DivX, for instance, the player will need to have that codec installed in order to view the video.

NOTE: Since the video must play at your game's colour depth, you may notice that in a 256-colour game it is very difficult to get a video that looks good, due to the attempt to reduce the depth of the video on the fly. FLIC may be a better choice for 256-colour games.

Cross-Platform Support

Windows: Yes
MS-DOS: No
Linux: No

Example:

PlayVideo ("intro.mpg", 1, 1);

See Also: PlayFlic

SeekMIDIPosition

SeekMIDIPosition (int position)

Example:

SeekMIDIPosition(60);

See Also: GetMIDIPosition

SeekMODPattern

SeekMODPattern (int pattern)

Example:

SeekMODPattern(30);

SeekMP3PosMillis

SeekMP3PosMillis (int position)

If the background music is currently crossfading between two tracks, this acts on the new track which is fading in.

Example:

SeekMP3PosMillis(30000);

See Also: GetMP3PosMillis

SetChannelVolume

SetChannelVolume (int channel, int volume)

This command adjusts the volume of the specified channel relative to the other channels. It is still constrained within the master volume, set by SetDigitalMasterVolume and SetMusicMasterVolume.

NOTE: This command only affects the current sound being played on the channel. If you start a new sound on the channel using PlaySoundEx for instance, then the channel volume will be changed back to the main Sound Volume setting.

See PlaySoundEx for more on sound channels.

Example:

SetChannelVolume (3, 255);

See Also: SetDigitalMasterVolume, SetMusicMasterVolume, SetSoundVolume

SetDigitalMasterVolume

SetDigitalMasterVolume (int volume)

Example:

SetDigitalMasterVolume(80);

See Also: SetMusicMasterVolume

SetFrameSound

SetFrameSound (int view, int loop, int frame, int sound)

Pass SOUND as 0 to disable the sound for this frame.

Example:

SetFrameSound (5, 1, 3, 0);

SetMusicMasterVolume

SetMusicMasterVolume (int volume)

Example:

SetMusicMasterVolume(80);

See Also: SetMusicVolume

SetMusicRepeat

SetMusicRepeat (int loopflag)

This function must be called BEFORE PlayMusic - it sets whether future music tracks will repeat or not.

Example:

SetMusicRepeat(1);

See Also: SetMusicVolume

SetMusicVolume

SetMusicVolume (int volume)

NOTE: The volume will be reset when the player enters a new room.

Example:

SetMusicVolume(-3);

See Also: SetMusicMasterVolume, SetSoundVolume, GetCurrentMusic

SetSoundVolume

SetSoundVolume (int volume)

Example:

SetSoundVolume(230);

See Also: SetMusicVolume

SetSpeechVolume

SetSpeechVolume (int volume)

Example:

SetSpeechVolume(200);

See Also: SetMusicVolume, SetSoundVolume

SetVoiceMode

SetVoiceMode (VoiceMode)

Valid values are:

eSpeechTextOnly      no voice, text only
eSpeechVoiceAndText  both voice and text
eSpeechVoiceOnly     voice only, no text

Example:

if (IsSpeechVoxAvailable()==1)
    SetVoiceMode(eSpeechVoiceAndText); 

StopAmbientSound

StopAmbientSound (int channel)

See Also: PlayAmbientSound

StopChannel

StopChannel (int channel)

See the description of PlaySoundEx for more on sound channels.

Example:

StopChannel (3);

See Also: IsChannelPlaying, PlaySoundEx

StopMusic

StopMusic ()

If there are tracks queued with PlayMusicQueued, then they are all cancelled.

Example:

StopMusic();

Browser Based Help. Published by chm2web software.