# Movie

Ren'Py is capable of using FFmpeg (included) to play movies using the video codecs:

- AV1

- VP9

- VP8

- Theora

- MPEG-4 part 2 (including Xvid and DivX)

- MPEG-2

- MPEG-1

and the following audio codecs:

- Opus

- Vorbis

- MP3

- MP2

- FLAC

- PCM

inside the following container formats:

- WebM

- Matroska

- Ogg

- AVI

- Various kinds of MPEG stream.

(Note that using some of these formats may require patent licenses. When in doubt, and especially for commercial games, we recommend using AV1, VP9, VP8, or Theora; Opus or Vorbis; and WebM, Matroska, or Ogg.)

Movies can be displayed fullscreen or in a displayable. Fullscreen movies are more efficient. YUV444 movies are not hardware accelerated, use YUV420 or YUV422 instead.

Ren'Py's movie decoder does not support movies with alpha channels, but the side_mask parameter of the `Movie()` displayable can be used for that purpose. Here is an example of how to use ffmpeg to create a webm file with a side-by-side mask from a mov file with an alpha channel.

    ffmpeg -i original.mov -filter:v alphaextract mask.mov
    ffmpeg -i original.mov -i mask.mov -filter_complex "hstack" -codec:v vp8 -crf 10 output.webm

Movies are supported on the Web platform, but the list of supported codecs differs from browser to browser. For cross-browser compatibility (especially to support Safari), the most efficient combination is H.264 with MP3 (or AAC) in a MP4 file. However, Ren'Py does not support H.264 decoding (or AAC), so this combination can only work on the Web platform.

## Fullscreen Movies

The easiest and most efficient way to display a movie fullscreen is to use the `renpy.movie_cutscene()` function. This function displays the movie fullscreen until it either ends, or the player clicks to dismiss it.

    $ renpy.movie_cutscene("On_Your_Mark.webm")

## Movie Displayables and Movie Sprites

The Movie displayable can be used to display a movie anywhere Ren'Py can show a displayable. For example, a movie can be displayed as the background of a menu screen, or as a background.

The Movie displayable can also be used to define a movie sprite, which is a sprite that is backed by two movies. The primary movie provides the color of the sprite. A second movie, the mask movie, provides the alpha channel, with white being full opacity and black being full transparency.

Movies played by the Movie displayable loop automatically.

Here's an example of defining a movie sprite:

    image eileen movie = Movie(play="eileen_movie.webm", side_mask=True)

The movie sprite can be shown using the show statement, which automatically starts the movie playing. It will be automatically stopped when the displayable is hidden.

    show eileen movie

    e "I'm feeling quite animated today."

    hide eileen

    e "But there's no point on wasting energy when I'm not around."

A Movie displayable can also be used as part of a screen, provided it is created during the init phase (for example, as part of an image statement.)

    image main_menu = Movie(play="main_menu.ogv")

    screen main_menu:
        add "main_menu"
        textbutton "Start" action Start() xalign 0.5 yalign 0.5

Multiple movie displayables or sprites can be displayed on the screen at once, subject to system performance, and provided all share the same framerate. The behavior of Ren'Py when displaying movies with different framerates is undefined, but will likely include a significant amount of frame drop.

## Python Functions

renpy.movie_cutscene(filename, delay=None, loops=0, stop_music=True)

  This displays a movie cutscene for the specified number of seconds. The user can click to interrupt the cutscene. Overlays and Underlays are disabled for the duration of the cutscene.

  filename

    The name of a file containing any movie playable by Ren'Py.

  delay

    The number of seconds to wait before ending the cutscene. Normally the length of the movie, in seconds. If None, then the delay is computed from the number of loops (that is, loops + 1) * the length of the movie. If -1, we wait until the user clicks.

  loops

    The number of extra loops to show, -1 to loop forever.

  Returns True if the movie was terminated by the user, or False if the given delay elapsed uninterrupted.

class Movie(*, size=None, channel='movie', play=None, side_mask=False, mask=None, mask_channel=None, start_image=None, image=None, play_callback=None, loop=True, group=None, **properties)

  This is a displayable that shows the current movie.

  size

    This should be specified as either a tuple giving the width and height of the movie, or None to automatically adjust to the size of the playing movie. (If None, the displayable will be (0, 0) when the movie is not playing.)

  channel

    The audio channel associated with this movie. When a movie file is played on that channel, it will be displayed in this Movie displayable. If this is left at the default of "movie", and play is provided, a channel name is automatically selected, using `config.single_movie_channel` and `config.auto_movie_channel`.

  play

    If given, this should be the path to a movie file, or a list of paths to movie files. These movie files will be automatically played on channel when the Movie is shown, and automatically stopped when the movie is hidden.

  side_mask

    If true, this tells Ren'Py to use the side-by-side mask mode for the Movie. In this case, the movie is divided in half. The left half is used for color information, while the right half is used for alpha information. The width of the displayable is half the width of the movie file.

    Where possible, side_mask should be used over mask as it has no chance of frames going out of sync.

  mask

    If given, this should be the path to a movie file, or a list of paths to movie files, that are used as the alpha channel of this displayable. The movie file will be automatically played on movie_channel when the Movie is shown, and automatically stopped when the movie is hidden.

  mask_channel

    The channel the alpha mask video is played on. If not given, defaults to channel_mask. (For example, if channel is "sprite", mask_channel defaults to "sprite_mask".)

  start_image

    An image that is displayed when playback has started, but the first frame has not yet been decoded.

  image

    An image that is displayed when play has been given, but the file it refers to does not exist. (For example, this can be used to create a slimmed-down mobile version that does not use movie sprites.) Users can also choose to fall back to this image as a preference if video is too taxing for their system. The image will also be used if the video plays, and then the movie ends, unless group is given.

  play_callback

    If not None, a function that's used to start the movies playing. (This may do things like queue a transition between sprites, if desired.) It's called with the following arguments:

    old

      The old Movie object, or None if the movie is not playing.

    new

      The new Movie object.

    A movie object has the play parameter available as `_play` while the ``channel`, `loop`, `mask`, and `mask_channel` fields correspond to the given parameters. If the loop field is a movie file, that movie is available as `_queue`.

    Generally, this will want to use `renpy.music.play()` to start the movie playing on the given channel. A minimal implementation is:

        def play_callback(old, new):

            if new.mask:
                renpy.music.play(new.mask, channel=new.mask_channel, loop=new.loop)

            renpy.music.play(new._play, channel=new.channel, loop=new.loop)

            if new._queue:
                renpy.audio.music.queue(new._queue, channel=new.channel, loop=True)

  loop

    If False, the movie will not loop. If True, the movie will loop. If a string, this is a second movie file that will be looped after the file given to play finishes.

    When loop is False, if image is defined, the image will be displayed when the movie ends. Otherwise, the displayable will become transparent.

  group

    If not None, this should be a string. If given, and if the movie has not yet started playing, and another movie in the same group has played in the previous frame, the last frame from that movie will be used for this movie. This can prevent flashes of transparency when switching between two movies.

  keep_last_frame

    If true, and the movie has ended, the last frame will be displayed, rather than the movie being hidden. This only works if loop is false. (This behavior will also occur if group is set.)

  oversample

    If this is greater than 1, the movie is considered to be oversampled, with more pixels than its logical size would imply. For example, if an movie file is 1280x720 and oversample is 2, then the image will be treated as a 640x360 movie for the purpose of layout.

    If None, Ren'Py will automatically determine oversamping. If an @ followed by a number is found in the filename, that number will be used as the the oversampling factor. Otherwise, Ren'Py will search for files and use those.

    Specifically, if :file`launch.webm` is used, Ren'Py will search for `launch@2.webm` if the movie is scaled up more than 1x, and `launch@4.webm` and `launch@3.webm` if the movie is scaled up more than 2x.

    Automatic oversampling of movies only happens when the movie begins playing.