6-2. 시퀀서 스크립팅 | UE5 Sequencer Deep Dive

01

Python 시퀀서 API

unreal 모듈을 활용한 시퀀서 스크립팅

UE5의 Python 스크립팅으로 시퀀서를 프로그래밍으로 제어할 수 있습니다. 대량의 시퀀스 생성, 트랙 추가, 키프레임 설정을 자동화합니다.

플러그인 활성화

"Python Editor Script Plugin"과 "Sequencer Scripting" 플러그인을 활성화해야 합니다. Output Log 하단의 Python 콘솔 또는 Editor Utility Widget에서 스크립트를 실행합니다.

Python - 시퀀스 생성 및 트랙 추가
import unreal

# 새 Level Sequence 생성
asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
sequence = asset_tools.create_asset(
    "NewSequence",
    "/Game/Cinematics/",
    unreal.LevelSequence,
    unreal.LevelSequenceFactoryNew()
)

# MovieScene 접근
movie_scene = sequence.get_movie_scene()

# 디스플레이 레이트 설정 (24fps)
movie_scene.set_display_rate(unreal.FrameRate(24, 1))

# 재생 범위 설정 (0~240 프레임 = 10초 at 24fps)
movie_scene.set_playback_range(0, 240)

# Camera Cut 트랙 추가
camera_cut_track = movie_scene.add_camera_cut_track()

# Fade 트랙 추가
fade_track = movie_scene.add_master_track(
    unreal.MovieSceneFadeTrack)

unreal.log("Sequence created successfully!")

02

바인딩과 키프레임 스크립팅

Python으로 액터 바인딩 및 키프레임 생성

Python - 액터 바인딩 및 Transform 키프레임
import unreal

# 기존 시퀀스 로드
sequence = unreal.load_asset("/Game/Cinematics/MySequence")
movie_scene = sequence.get_movie_scene()

# 월드에서 액터 찾기
editor_subsystem = unreal.get_editor_subsystem(
    unreal.EditorActorSubsystem)
actors = editor_subsystem.get_all_level_actors()

target_actor = None
for actor in actors:
    if actor.get_actor_label() == "MyCharacter":
        target_actor = actor
        break

# Possessable 바인딩 추가
binding = sequence.add_possessable(target_actor)

# Transform 트랙 추가
transform_track = binding.add_track(
    unreal.MovieScene3DTransformTrack)

# 섹션 추가 (전체 범위)
section = transform_track.add_section()
section.set_range(0, 240)

# 채널 접근 (Location X, Y, Z, Rotation X, Y, Z, Scale X, Y, Z)
channels = section.get_all_channels()
# channels[0] = Location.X
# channels[1] = Location.Y
# channels[2] = Location.Z

# 키프레임 추가
channels[0].add_key(unreal.FrameNumber(0), 0.0)
channels[0].add_key(unreal.FrameNumber(120), 500.0)
channels[0].add_key(unreal.FrameNumber(240), 0.0)

대량 작업 자동화

Python 스크립팅은 수십 개의 시퀀스를 일괄 생성하거나, 모든 샷의 카메라 설정을 한 번에 변경하는 등 대량 작업에 특히 유용합니다. 에디터 시작 시 자동 실행되도록 스크립트를 등록할 수도 있습니다.

03

Editor Utility Widget

커스텀 시퀀서 편집 도구 제작

Editor Utility Widget (EUW)을 사용하면 시퀀서 작업을 위한 커스텀 UI 도구를 Blueprint로 만들 수 있습니다. 버튼 클릭으로 복잡한 시퀀서 조작을 수행합니다.

EUW 활용 예시

일괄 카메라 설정

모든 샷의 Cine Camera에 동일한 FilmBack, F-Stop, Focus 설정을 일괄 적용하는 도구

시퀀스 리포트

마스터 시퀀스의 모든 샷 길이, 카메라, 프레임 범위를 CSV로 내보내는 도구

키프레임 유틸리티

선택한 트랙의 모든 키프레임을 특정 프레임만큼 이동하거나, 보간 모드를 일괄 변경하는 도구

MRQ 배치 설정

여러 시퀀스를 MRQ에 자동 등록하고 렌더 설정을 일괄 적용하는 도구

Python - MRQ 자동 렌더 제출
import unreal

# Movie Render Queue 서브시스템 접근
mrq_subsystem = unreal.get_editor_subsystem(
    unreal.MoviePipelineQueueSubsystem)
queue = mrq_subsystem.get_queue()

# 여러 시퀀스를 큐에 추가
sequences = [
    "/Game/Cinematics/SHOT_Intro_010",
    "/Game/Cinematics/SHOT_Intro_020",
    "/Game/Cinematics/SHOT_Intro_030",
]

for seq_path in sequences:
    job = queue.allocate_new_job(
        unreal.MoviePipelineExecutorJob)
    job.set_sequence(
        unreal.SoftObjectPath(seq_path))
    job.set_configuration(
        unreal.load_asset("/Game/Config/HighQuality"))

# 렌더 실행
executor = unreal.MoviePipelinePIEExecutor()
mrq_subsystem.render_queue_with_executor(executor)

unreal.log(f"Submitted {len(sequences)} jobs to MRQ")

04

자동화 파이프라인

커맨드렛과 CI/CD 연동

커맨드라인 시퀀서 자동화

커맨드라인 - Python 스크립트 실행
# 에디터 모드로 Python 스크립트 실행
UE5Editor.exe MyProject ^
    -ExecutePythonScript="Scripts/batch_render.py" ^
    -stdout -unattended -nopause

# 커맨드렛으로 MRQ 렌더
UE5Editor.exe MyProject ^
    -MoviePipelineConfig="/Game/Config/HighQuality.HighQuality" ^
    -LevelSequence="/Game/Cinematics/CIN_Trailer_Master" ^
    -game -MoviePipelineLocalExecutorClass= ^
    /Script/MovieRenderPipelineCore.MoviePipelineInProcessExecutor

CI/CD 파이프라인 예시

단계	도구	작업
1. 트리거	Jenkins / GitHub Actions	시퀀스 에셋 변경 감지
2. 빌드	UE5 빌드 서버	프로젝트 쿠킹
3. 렌더	MRQ + 커맨드라인	변경된 샷 자동 렌더
4. 업로드	Python 스크립트	렌더 결과물 ShotGrid/서버 업로드
5. 알림	Slack / Teams	팀에 렌더 완료 알림

ShotGrid 연동

ShotGrid(구 Shotgun) Python API와 UE5 Python 스크립팅을 결합하면 테이크 관리, 리뷰 제출, 승인 워크플로를 완전 자동화할 수 있습니다. 렌더 완료 후 자동으로 ShotGrid에 버전을 생성하고 리뷰어에게 알림을 보냅니다.

SUMMARY

핵심 요약

UE5 Python 스크립팅으로 시퀀스 생성, 트랙 추가, 키프레임 설정을 프로그래밍으로 자동화한다
unreal.LevelSequence, MovieScene, FrameNumber 등의 Python API로 시퀀서 데이터에 접근한다
Editor Utility Widget으로 커스텀 시퀀서 도구(일괄 설정, 리포트, 유틸리티)를 제작한다
MoviePipelineQueueSubsystem API로 MRQ 렌더 잡을 프로그래밍으로 제출한다
커맨드라인 실행으로 CI/CD 파이프라인에 시퀀서 렌더를 통합할 수 있다
ShotGrid 등 프로덕션 관리 도구와 연동하여 엔드 투 엔드 자동화를 구현한다

PRACTICE

도전 과제

배운 내용을 직접 실습해보세요

실습 1: Python 시퀀서 스크립팅 기본

UE5 Python Editor에서 시퀀서 API를 사용하여 Level Sequence 생성, Actor 바인딩, Transform 키프레임 자동 추가 스크립트를 작성하세요.

실습 2: 배치 편집 스크립트

Python으로 기존 시퀀스의 모든 CineCamera 샷에 대해 Focal Length를 일괄 변경하는 스크립트를 만드세요. 시퀀스를 순회하며 특정 프로퍼티를 수정하세요.

심화 과제: 시네마틱 파이프라인 자동화

외부 데이터(샷 리스트 CSV)를 읽어 시퀀스를 자동 구성하는 파이프라인을 Python으로 구축하세요. 카메라 배치, Actor 바인딩, 타이밍 설정을 자동화하세요.