影片 link

Ren’Py可以使用FFmpeg解碼器(已內建)播放以下影片編碼格式的影片：

  • AV1

  • VP9

  • VP8

  • Theora

  • MPEG-4 part 2 (包括Xvid和DivX)

  • MPEG-2

  • MPEG-1

及以下編碼格式的音訊：

  • OPUS

  • Vorbis

  • MP3

  • MP2

  • FLAC

  • PCM

還支持以下容器格式：

  • WebM

  • Matroska

  • Ogg

  • Avi

  • 多種MPEG編碼串流。

(注意某些格式可能需要專利許可證書。沒有把握的情況下，我們推薦使用AV1、VP9、VP8或者Theora、Opus、Vorbis，以及WebM、Matroska或者Ogg。)

影片可以全螢幕播放，也可以在一個可視組件內播放。全螢幕播放更省事。 YUV444不能使用硬體加速，需要使用YUV420或YUV422。

Ren’Py的影片解碼器不支持alpha通道，但使用可視組件 Movie() 的 side_mask 參數可以實現同樣效果。 下面的例子展示了如何利用ffmpeg庫，使用帶alpha通道的mov文件創建webm文件的四邊對齊(side-by-side)mask。

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

(譯者注，ffmpeg命令用於在操作系統shell或命令行模式中運行，對影片檔案重編碼。而不是用於Ren’Py腳本中。)

WebP平台可以播放影片，但各個瀏覽器支持的編碼格式會有差別。最常見的跨瀏覽器相容的組合是用H.264編碼影片用MP3(或AAC)編碼音訊封裝在MP4中。 不過，Ren’Py不支持H.264(或AAC)編碼，所以不能使用該組合。

全螢幕播放影片 link

全螢幕播放影片最簡單有效的辦法是，使用 renpy.movie_cutscene() 函數。該函數會全螢幕播放影片直到影片結尾。用戶也可以點擊直接跳過播放。

$ renpy.movie_cutscene("On_Your_Mark.webm")

在行動端平台，例如安卓和iOS，默認情況下配置項 config.hw_video 設為True，此時會啟用硬體影片解碼。硬體影片解碼效率更高，但具體支持的影片格式需要視具體平台而定。 這裡可以查看 安卓支持的媒體格式。 一個快速測試的辦法是，直接把影片檔案複製到手機上，然後使用預設的影片播放器看看能否播放。

Web平台不支持播放影片。

影片組件和影片精靈(sprite) link

任何可展示可視組件的地方，Ren’Py都可以使用影片組件實現影片的播放。例如，可以在菜單界面播放一個影片作為背景。

影片組件也能用於定義一個影片精靈(sprite)。影片精靈(sprite)由兩段影片組成。主影片提供精靈(sprite)的各種顏色資訊。次影片是一個遮罩影片，提供alpha通道資訊，白色表示完全不透明而黑色表示完全透明。

使用影片組件會自動循環播放。

影片組件有兩個參數：

play

該值是一個字串，給定了需要播放的影片檔案名。

必須提供的這個值。

mask

該值是一個字串，給定了alpha遮罩影片檔案名。它需要與 play 原影片的大小，時長，幀率相同。

這裡有一個定義影片精靈(sprite)的樣例：

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

影片精靈可以使用show語句顯示，並自動啟動影片播放。如果可視組件被隱藏時，影片播放會自動停止。

show eileen movie

e "我感覺自己今天很活躍。"

hide eileen

e "不過在我不出現的時候沒必要浪費力氣。"

影片組件也能被用作某個界面的一部分，在初始化階段定義即可(然後就可作為某個image語句的一部分)。

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

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

在同一個界面的同一時間可以顯示多個影片組件或影片精靈(sprite)。受到系統性能限制，多個影片播放時使用相同的幀率。Ren’Py中沒有定義過使用不同幀率播放影片的行為，很可能會導致很嚴重的掉幀。

python函數 link

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

該函數播放一個MPEG-1格式的過場。用戶可以使用點擊跳過該過場。頂層元素overlay和底層元素underlay在過場中依然顯示。

filename

含有MPEG-1影片的檔案名。

delay

過場結束前等待(用戶交互行為)的時間，單位為秒。通常就是影片長度，以秒計。若該值為None，delay值會被自動計算，使用循環總次數(即入參loop+1)乘以影片總時長。若該值為-1，則會一直等待用戶點擊。

loops

該值表示，除了首次播放之外，額外循環播放的次數。若值為-1表示始終循環播放。

若影片播放被用戶停止則返回True，若在delay定義的預計時間內由於其他原因中斷播放則返回False。

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) link

該類是一個可視組件，用於顯示影片。

size

該參數有兩種情況：指定一個包含指定影片寬度和高度的元組，或空值(None)自適應影片原尺寸。 (如果這裡設置為None，可視組件在不播放影片時的值就是(0, 0)。)

channel

與播放影片相關聯的音訊通道名。當某個影片在該通道上播放時，就會在對應的影片組件上顯示。 如果該參數為預設值“movie”，並且 play 參數提供了播放檔案名的情況下， 會根據 config.single_movie_channel 和 var:config.auto_movie_channel 自動選擇可用的通道名。

play

若給定入參play，其應該是某個影片檔案的路徑。顯示影片時，入參channel通道上的影片檔案將會自動播放。當影片被隱藏時，影片檔案會自動停止播放。

side_mask

若為True，Ren’Py會將該Movie對象設置為水平並排(side-by-side)mask模式。 Movie對象將被對等分割為兩部分。左半為顏色資訊，右半為alpha通道資訊。對應的可視組件寬度也為該影片檔案的一半。

盡可能使用 mask 而不是 side_mask ，除非有幀同步問題。

mask

若給定入參mask，其應是某個影片檔案的路徑，而這個影片用作可視組件的alpha通道。影片被顯示時，在mask_channel通道上的影片檔案將會自動播放。當影片被隱藏時，影片檔案會自動停止播放。

mask_channel

alpha遮罩影片播放使用的通道。若未給定，預設會在入參channel後面加上 _mask 後綴，註冊一個新的通道。(例如，若入參channel名為“sprite”，那麼自動生成的mask_channel值就是“sprite_mask”。)

start_image

當影片開始播放，但第一幀畫面還未解碼時，會使用此圖像頂替。

image

若給定了參數play的值，但文件可能並不存在或不能播放的情況下，則會顯示入參image給定的圖片文件。(例如，這個功能可以用於創建一個精簡的行動版本，其不包含影片精靈。)當用戶遇到系統負荷過重時，也能在特性中選擇降低為顯示圖片而不是播放影片。

play_callback

若不是None，這個函數用於啟動影片的播放。(函數的工作可能是將一個轉場加入到各個sprite之間。)調用函數時使用下列入參：

old

舊的Movie對象，如果沒有播放影片則為None。

new

新的Movie對象。

Movie對象中的 play 參數值如果為 _play ，則 channel、loop、mask 和 mask_channel 欄位則與同名參數一一對應。

如果想要使用 renpy.music.play() 在指定的通道啟動影片播放的話，帶上synchro_start=True。最小化實現代碼如下：

def play_callback(old, new):

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

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

若為False，不會循環播放影片。如果 image 已定義，影片播放結束後將顯示對應圖片。否則，影片播放結束後將變成透明畫面。

group

若不是None，此入參應該是一個字串。當某個影片還未開始播放時， 如果前一幀同組的其他影片還處於播放狀態，那就會把前一幀的畫面作為當前影片的初始畫面。 該功能用於避免影片切換時導致的透明閃爍。

keep_last_frame

若為True，在影片播放結束後，將顯示最後一幀畫面，而不是隱藏影片。前提需要把 loop 設置為False。 (group 設置為非None值後也能生效。)