Skip to content
SupportOpen app

Scripting the plugin

Drive the plugin from Python: set up markers, link a sequence, sync it and render its clips. Every function goes through the same code as the matching toolbar or track menu command, with the same rules.

  1. Go to Edit → Plugins, enable Python Editor Script Plugin, and restart the editor.
  2. Open the Output Log. Switch its command box from Cmd to Python to type Python, or run a script file from Cmd with py "C:/Scripts/my_script.py".
  3. Sign in to Screel from the level toolbar. See Sign in. For jobs without a browser, sign in with an API key instead; see Sign in with an API key.

Python sees the library as unreal.ScreelEditorLibrary, with snake_case names:

import unreal
lib = unreal.ScreelEditorLibrary
print(lib.is_signed_in(), lib.get_signed_in_user_name())

sequence is an unreal.LevelSequence, for example from unreal.load_asset("/Game/Cinematics/MySequence"). A marker is an unreal.MovieSceneScreelSection.

Function Behaviour
is_signed_in() Returns bool. True while the editor holds a Screel session.
is_signed_in_with_api_key() Returns bool. True when the editor signed in with an API key.
get_signed_in_user_name() Returns str. The display name of the signed-in user. Empty when signed out or before the profile loads.
open_sequence(sequence) Returns bool. Opens the sequence in Sequencer, shows its root and makes it the sequence Screel follows. False when the sequence cannot open.
ensure_track(sequence) Returns MovieSceneScreelTrack. The Screel markers track of the sequence, created when missing. None without a sequence.
add_marker(sequence, start_seconds, length_seconds) Returns MovieSceneScreelSection. Takes whole seconds. Adds a marker like Add marker at playhead, then moves its end like a drag of the right grip. Creates the track when missing. None when the rules refuse it: a start below 0, a length outside 3 to 10 seconds, or a marker that already starts there. When a touching next marker cannot give or take enough time, the new marker gets another length and the log warns. The marker starts with its still key on its first frame.
add_key(marker, seconds_from_start) Returns bool. Takes whole seconds. Adds a key seconds_from_start seconds into the marker, like Add key at playhead with the playhead there. False when that second lies outside the span. False when the marker already holds five keys, its still key included, or has no free frame.
link_sequence(sequence, project_id, seed_mode="none") Returns bool. Links the sequence to a project without opening the browser. seed_mode is "cuts" (like Markers from camera cuts), "whole" (one marker for the whole sequence) or "none". True when the link request starts, or when the sequence already links to that project. False when signed out, when project_id is empty or seed_mode is unknown, or when the sequence cannot open. False when the sequence links to another project (unlink it first).
is_linked(sequence) Returns bool. True when the sequence’s Screel track carries a project link.
get_linked_project_id(sequence) Returns str. The project the sequence links to. Empty when it is not linked.
sync_now(sequence) Returns int. Opens and focuses the sequence, then works like Sync now: queues every marker and syncs. Returns the count queued. 0 when signed out, not linked, or the sequence cannot open.
get_pending_sync_count(sequence) Returns int. Markers still waiting to reach Screel. 0 means synced. -1 when the sequence is not the open, linked one.
render_clips(sequence, marker_ids) Returns bool. Opens and focuses the sequence, then works like Render all clips to Screel: renders the clips through Movie Render Queue, uploads them and syncs. Pass an empty list to render every marker. Python cannot read marker ids, so a script always passes an empty list. True when the batch starts. False when signed out, not linked, a render already runs, or the sequence cannot open.
is_rendering_clips() Returns bool. True while a clip render or a still render runs.
get_last_clip_render_error() Returns str. The error of the last render_clips batch. Empty while it runs and after it succeeds.
get_last_clip_render_synced_count() Returns int. The markers whose clip reached Screel in the last render_clips batch.

Every refusal logs a warning under LogScreelScripting in the Output Log, and the warning says which rule refused the call.

The project id is the last part of the project’s address in the Screel editor, https://screel.ai/editor/<project id>. For a sequence you linked in the Sequencer toolbar, get_linked_project_id returns it.

This script opens a sequence, makes sure it has a Screel track, adds three markers and a key, links the sequence to a project, syncs it, and waits until no marker is pending. Set SEQUENCE_PATH and PROJECT_ID first.

import time
import unreal
SEQUENCE_PATH = "/Game/Cinematics/Canyon_Seq"
PROJECT_ID = "your-project-id"
TIMEOUT_SECONDS = 120
lib = unreal.ScreelEditorLibrary
if not lib.is_signed_in():
raise RuntimeError("Sign in to Screel from the level toolbar first.")
sequence = unreal.load_asset(SEQUENCE_PATH)
if not isinstance(sequence, unreal.LevelSequence):
raise RuntimeError(f"{SEQUENCE_PATH} is not a Level Sequence.")
if not lib.open_sequence(sequence):
raise RuntimeError("Could not open the sequence. See LogScreelScripting.")
lib.ensure_track(sequence)
markers = [
lib.add_marker(sequence, 0, 4),
lib.add_marker(sequence, 4, 5),
lib.add_marker(sequence, 9, 4),
]
if any(marker is None for marker in markers):
raise RuntimeError("A marker was refused. See LogScreelScripting.")
if not lib.add_key(markers[0], 2):
raise RuntimeError("The key was refused. See LogScreelScripting.")
if not lib.link_sequence(sequence, PROJECT_ID, "none"):
raise RuntimeError("The link did not start. See LogScreelScripting.")
class WaitForSync:
def __init__(self):
self.deadline = time.monotonic() + TIMEOUT_SECONDS
self.syncing = False
self.handle = unreal.register_slate_post_tick_callback(self.tick)
def stop(self, message):
unreal.unregister_slate_post_tick_callback(self.handle)
unreal.log(message)
def tick(self, delta_seconds):
if time.monotonic() > self.deadline:
self.stop("Gave up waiting for Screel.")
elif not self.syncing:
if lib.is_linked(sequence):
queued = lib.sync_now(sequence)
unreal.log(f"Linked. Queued {queued} markers.")
self.syncing = True
else:
pending = lib.get_pending_sync_count(sequence)
if pending == 0:
self.stop("All markers synced.")
elif pending < 0:
self.stop("The sequence is no longer the open, linked one.")
waiter = WaitForSync()

To render the clips after the sync, raise TIMEOUT_SECONDS, because a render takes longer than a sync. Set self.rendering = False in __init__, then use this tick:

def tick(self, delta_seconds):
if time.monotonic() > self.deadline:
self.stop("Gave up waiting for Screel.")
elif self.rendering:
if not lib.is_rendering_clips():
error = lib.get_last_clip_render_error()
self.stop(error or "All clips reached Screel.")
elif not self.syncing:
if lib.is_linked(sequence):
queued = lib.sync_now(sequence)
unreal.log(f"Linked. Queued {queued} markers.")
self.syncing = True
else:
pending = lib.get_pending_sync_count(sequence)
if pending == 0:
if lib.render_clips(sequence, []):
self.rendering = True
else:
self.stop("The render did not start. See LogScreelScripting.")
elif pending < 0:
self.stop("The sequence is no longer the open, linked one.")

When the script finishes, the three markers are scenes in the project, and the first scene has a keyframe at 2 seconds. To see them, choose Open scene in Screel on a marker; see Markers and sync.