Copyright © 2025-2026 Candy ArtsMedia Play
The Media_Play command plays a file on one or more media players. The type of media depends on the player: audio players play sounds, video players play videos, and image players display still images or frame animations. All players start at the same time, and the Dialogue resumes once each one with a Wait_Loops or Wait_Time has played for that duration. A Private player only accepts commands from the Engine that owns it, while a Public player accepts them from any Engine, within the limits of its Public Mode (see Media Players).
Keys
Every key also accepts a ¢ expression instead of a fixed value, unless its description says otherwise. See CandyRef Expressions.
Players
Description:
The media players to act on. Each key is a player's name, and its value is a Dictionary of settings for that player (see below), or an empty Dictionary for none. A single Line can control several players, each with its own settings. An entry that can't be found is reported and skipped, without affecting the others.
Values:
• Player name: A key of the Engine's media_players_paths, such as Music or Video. It also names the subfolder of the audio, video or image folder that the player's files are loaded from.
• ¢ expression: Can also return the player node itself, such as ¢$UI/Radio.
Player Settings
Each player in Players accepts the following keys. Some apply only to certain types of player.
File
Description:
The file to play, loaded from the player's folder: {audio_folder}/{player}, {video_folder}/{player} or {image_folder}/{player}, as set in Candy_Properties.gd. See Media Files.
Values:
• File name: Such as Theme. When the name has no extension, the player's default extension is added (.ogg for audio, .ogv for video, .png for images). When the file doesn't exist, the player's Default file is loaded instead.
• Folder name: On image players, a frame-by-frame animation. A config.txt file in the folder containing fps = N sets its frame rate.
• res:// or user:// path: Loaded from that path, with no fallback to Default.
• Empty: Default.
• ¢ expression: Can also return a loaded resource, such as ¢load("res://Music/Boss.ogg").
Loops
Description:
The number of times the media plays.
Values:
• Positive number: Play that many times.
• 0: Hold the first frame without playing, unless a Duration is set. There is nothing to wait for until a Media_Resume starts playback, which then plays once. On audio players, nothing plays at all.
• -1 or any negative number: Loop indefinitely, whatever the Duration.
• Empty: 1.
Duration
Description:
The time the media continues to play after its Loops, so that it can stop partway through a loop. The media plays for Loops × its length + Duration: with a Loops of 0, it plays for the Duration alone. A duration longer than the media carries over into additional loops. When the time runs out, the playback ends as if its last loop had finished, on its Stop_Frame. Paused time doesn't count.
A static image has no loops: it remains on screen for its Duration, or until Media_Stop if it has none.
Values:
• Number of seconds: Such as 2.5.
• Timestamp: In the format SS.xx, MM:SS.xx or HH:MM:SS.xx, such as 01:30.5.
• f=N: N frames, on video and animated image players only. Frames are counted as for Wait_Time.
• 0, null or empty: No duration: Loops alone decides.
Stop_Frame
Description:
The frame each player stops on once it has played its Loops and Duration, as a Media_Stop with the same value would stop it. Audio has no frames to display: on an audio player, any number stops the playback and leaves its file loaded.
Values:
• Clear or X (case-insensitive): Unload the file. Video and image players are also hidden; the dialogue UI retains its z index.
• 0: Stop on the frame it ends on. Video and image players remain on screen, and Media_Resume doesn't restart them.
• -1: Stop on the last frame, with the same behavior as 0.
• Positive number: Stop on that frame, counted from 1, with the same behavior as 0. Video frames count at FPS, else the video's own frame rate.
• Empty: Clear.
Wait_Loops
Description:
The number of completed loops the Dialogue waits for before resuming. The Dialogue resumes after Wait_Loops loops plus Wait_Time into the following loop, or earlier if playback ends or is stopped. When several entries of the Line have a wait, the Dialogue resumes once all of them have reached it.
Values:
• 0: Don't wait for any loops. If Wait_Time is also 0, the Dialogue doesn't wait at all.
• Positive number: The number of loops to wait for.
Wait_Time
Description:
The additional time the Dialogue waits after Wait_Loops, measured into the following loop. A time longer than the media carries over into additional loops.
Values:
• Number of seconds: Such as 2.5.
• Timestamp: In the format SS.xx, MM:SS.xx or HH:MM:SS.xx, such as 01:30.5.
• f=N: N frames, on video and image players only, since audio has no frames. A video counts frames at its own frame rate, and an animated image at its playback frame rate.
• 0 or empty: No additional wait.
FPS
Description:
Video and image players only. For a video, the frame rate used to count f= values, overriding the video's own. For an animated image, its playback frame rate, overriding every default.
Values:
• Frames per second: Such as 24.
• Empty: The media's own frame rate, otherwise the default frame rate.
Animated
Description:
Image players only. Whether File must be a frame animation or a single image.
Values:
• -1: Either, as File says: a folder is an animation, and a file is a single image.
• 1: File must be a folder.
• 0: File must be a single image.
• Empty: -1.
Box
Description:
Changes the z index of the dialogue UI relative to this player, so the Dialogue can be drawn in front of or behind it. The dialogue box with its portrait, the subtitles, the chat and barks all move together. Video and image players only.
Values:
• Empty: Leave the z index unchanged, so that several players in the same Line don't override each other.
• Reset (case-insensitive): Restore each UI element's default z index.
• Number: Set the z index to exactly that value, such as 150.
• +N / -N: The player's z index plus or minus N. For example, +1 draws the dialogue in front of the player.
Take_Hold
Description:
Whether this command takes hold of the player, if it is Public. While an Engine holds it, its Public Mode determines what other Engines can do with it: nothing (Exclusive), only the commands it lists (Semi-Exclusive), or anything (Free). The hold lasts until the playback ends or is stopped.
Values:
• Empty: The player decides, from its own list of commands that take hold.
• 1: Take hold, even if the player doesn't list this command.
• -1: Never take hold.