CLI Tool

FCS CLI tool provides a script-based interface for automating facial capture and animation processing workflows. It allows you to load sessions, modify session properties, process videos, and upload animations to Maya—all through a simple YAML script format.

Table of Contents

Installation
Quick Start
Script Format
- Validation Strictness
- Profiles
Execution Model
Commands
Step Types
Examples
Logging
Error Handling
Maya Integration
Troubleshooting

Installation

The CLI tool is part of the FCS (Facial Capture System) package starting from FCS 26.04. It is automatically installed when you install FCS.

Quick Start

Create a YAML script file (e.g., my_script.yaml):

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"
  wait_seconds_after_scene_open: 2.0  # Optional: wait 2 seconds after scene opens
  fisheye: true  # Optional: enable fisheye correction
  pipeline: "Rich"  # Optional: use Rich pipeline
  denoising: "my_profile"  # Optional: load denoising profile from presets
  initial_scene_open: true  # Optional: open scene after validation (default: true)
  command_port: 42069  # Optional: Maya commandPort for all operations
  rename_controllers:  # Optional: modify controller name prefixes
    prefix: "char_face_"
    action: "prepend"  # or "remove"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true
        audio: true
      overrides:
        command_port: 42070  # Optional: use different port for this step

Run the script:

FCS_CLI.exe --file my_script.yaml

Script Format

Top-Level Structure

Every script must have three required sections:

version: 1                    # Required: Must be exactly 1
context:                     # Required: Script context
  session: <string>          # Required: Path to fcs_session.yaml
steps:                       # Required: List of steps to execute
  - <step>                   # One or more steps

Version

Currently, only version 1 is supported. This field ensures forward compatibility as the script format evolves.

Context

The context section defines the session file to load at the start of script execution.

session (required, string): Path to the FCS session YAML file. Must point to a file named exactly fcs_session.yaml; any other filename will fail validation.
wait_seconds_after_scene_open (optional, float): Global sleep time in seconds to wait after a Maya scene is opened. This applies to all scene opening operations in the script, including when scenes are opened via reopen_maya_scene in process steps or when Maya launches with a scene. Default: 0.0 (no wait)
fisheye (optional, bool): Enable or disable fisheye correction for video processing. If provided, overrides the UI setting. Default: true
pipeline (optional, string): Processing pipeline to use for video processing. Must be one of: "Rich", "Robust", "RP", "RP++", "Robust++", "Rich++". If provided, overrides the UI setting. Default: "RP++"
denoising (optional, string): Path to a denoising/smoothing profile file, or a filename to load from the smoothing presets directory. If it’s a full path, it must exist. If it’s just a filename (not a full path), it will be loaded from FCS_TMP_DIR/smoothing_presets/filename.yaml. If provided, loads the profile before processing. Default: No Smoothing
command_port (optional, integer): Maya commandPort number to use for all Maya operations in the script. Must be an integer between 1 and 65535. If provided, recreates the connection with the specified port and uses it for all Maya preflight checks and uploads. Default: 42069.
initial_scene_open (optional, bool): If true (the default), automatically opens the Maya scene once after data validation and before running all steps. The scene is opened only once at the start of script execution (after the preflight check), not before each step. If false, skips the initial scene opening. Default: true (scene will be opened automatically if maya_scene and maya_base are set in the session).
rename_controllers (optional, mapping): Modify controller names by prepending or removing a prefix. This is applied once after the session is loaded, before any steps execute. Useful for adapting controller names to match Maya scene naming conventions.
- prefix (required, string): The prefix to prepend or remove from all controller names
- action (optional, string): Operation to perform - "prepend" (default) or "remove"
playblast (optional, mapping): Override playblast settings for all process steps that export playblast. If not set, application settings are used.
- camera (optional, string): Maya camera name (e.g. "persp").
- width (optional, integer): Output width in pixels.
- height (optional, integer): Output height in pixels.
- percent (optional, integer): Resolution percent (e.g. 100, must be 1–100).
- quality (optional, integer): Playblast quality (e.g. 100, must be 1–100).
profiles (optional, list): Rules to enable/disable ROM profiles in the loaded session before any steps run. See Profiles for full details.

Steps

Steps are executed sequentially in the order they appear. Each step must be a single-key mapping with one of these keys:

process - Process a video and optionally upload to Maya
sleep - Pause script execution for a specified duration

Validation Strictness

Script validation follows a strict schema contract. The validator rejects any deviation from the defined schema:

Unknown top-level fields → error: Only version, context, and steps are allowed at the top level. Any other field will cause validation to fail.
Unknown context fields → error: Only the documented context fields are allowed. Unknown fields in the context section will cause validation to fail.
Unknown step types → error: Only process and sleep are valid step types. Any other step type will cause validation to fail.
Unknown step fields → error: Each step type has a defined set of allowed fields. Any field not explicitly documented for that step type will cause validation to fail.
Extra keys in nested structures → error: Nested structures (like upload in process steps, or overrides) only accept their documented fields. Unknown keys will cause validation to fail.
Order matters: Steps are executed sequentially in the exact order they appear in the steps list. The execution order is significant and cannot be changed.

Examples of validation failures:

# ❌ Invalid: Unknown top-level field
version: 1
context:
  session: "path/to/session.yaml"
steps: []
unknown_field: "value"  # Error: unknown top-level field

# ❌ Invalid: Unknown context field
version: 1
context:
  session: "path/to/session.yaml"
  unknown_context_field: "value"  # Error: unknown context field
steps: []

# ❌ Invalid: Unknown step type
version: 1
context:
  session: "path/to/session.yaml"
steps:
  - unknown_step: {}  # Error: unknown step type

# ❌ Invalid: Unknown step field
version: 1
context:
  session: "path/to/session.yaml"
steps:
  - process:
      video: "path/to/video.mp4"
      unknown_field: "value"  # Error: unknown field in process step

# ❌ Invalid: Unknown nested field
version: 1
context:
  session: "path/to/session.yaml"
steps:
  - process:
      video: "path/to/video.mp4"
      upload:
        animation: true
        unknown_upload_field: true  # Error: unknown field in upload

Profiles

The profiles context field lets you enable or disable profiles in the session before any steps run. Rules are applied sequentially — later rules override earlier ones for the profiles they match.

Each rule has three fields:

Field	Required	Values	Description
`match`	yes	`"all"` or a list of criteria	Which profiles to target
`select`	yes	`"all"`, `"none"`, or integer ≥ 1	What to do with matched profiles
`condition`	no	`AND` (default) or `OR`	How to combine multiple criteria

match criteria — each item in the list is a single-key mapping:

Key	Matches when…
`video: "<stem>"`	Profile’s source video filename (without extension) equals value
`not_video: "<stem>"`	Profile has no source video, or its stem differs from value
`user_tag: "<tag>"`	Profile has this user tag
`no_user_tag: "<tag>"`	Profile does NOT have this user tag

select values:

"all" — enable all matched profiles
"none" — disable all matched profiles
integer N — randomly enable N of the matched profiles (error if fewer than N matched)

Examples:

profiles:
  # Disable everything first
  - match: all
    select: none

  # Then enable exactly 10 profiles whose source video is "ROM_walk"
  - match:
      - video: "ROM_walk"
    select: 10

  # Enable all profiles tagged "hero" OR tagged "featured"
  - match:
      - user_tag: "hero"
      - user_tag: "featured"
    condition: OR
    select: all

  # Enable profiles tagged "validated" AND whose video is NOT "ROM_bad"
  - match:
      - user_tag: "validated"
      - not_video: "ROM_bad"
    condition: AND   # default, can be omitted
    select: all

Note: match must be a YAML list (using - items). A plain mapping is rejected to prevent YAML’s silent duplicate-key merging (e.g. two video: keys would collapse into one).

Execution Model

Understanding how scripts execute helps you write effective automation workflows. The FCS CLI follows a predictable execution model:

Execution Lifecycle

Script Initialization: The script is loaded and validated against the schema. Any schema error exits immediately with code 1 before any session or Maya operations occur.
License Check: License is checked out/validated. Failure exits with code 3.
Session Loading: The session file specified in context.session is loaded once. The session remains in memory throughout execution.
Controller Renaming: If rename_controllers is specified, controller name prefixes are prepended or removed once before any steps run.
Profile Selection: If profiles is specified, the rules are applied sequentially to set each ROM profile’s enabled state.
Affogato Initialization: A connection to Maya’s commandPort is established.
Maya Preflight: Maya reachability is verified. Failure exits with code 2 — no steps execute.
Initial Scene Opening: If initial_scene_open is true (the default) and the session has maya_scene and maya_base configured, the Maya scene is opened once before any steps run. Failures are non-fatal (logged as warnings). The script waits for wait_seconds_after_scene_open seconds after opening.
Step Execution: Steps execute sequentially in the order they appear. The license is re-checked before each step after the first. There is no rollback, branching, or parallelism.

Context and Overrides

Context Fields: All fields defined in the context section apply globally to all steps unless explicitly overridden. This includes settings like fisheye, pipeline, denoising, command_port, and playblast.
Step Overrides: The overrides section in a process step applies only for the duration of that specific step. After the step completes, the global context values are restored. This allows you to temporarily change settings (like command_port, maya_scene, or maya_base) for individual processing operations.

Execution Guarantees

Sequential Execution: Steps always execute one at a time, in order
No Rollback: If a step fails, execution stops; previous steps are not undone
No Branching: Conditional logic or loops are not supported
No Parallelism: Multiple steps cannot run simultaneously
Session Persistence: The session remains in memory throughout execution; changes are not persisted to disk

Commands

Run Script

Execute a YAML script:

FCS_CLI.exe --file <script_path>

Options:

--file, -f: Path to the YAML script file (required)
--dry-run: Validate the script without executing it

Examples:

# Run a script
FCS_CLI.exe --file my_script.yaml

# Validate without executing
FCS_CLI.exe --file my_script.yaml --dry-run

Step Types

`process` Step

Processes a single video file and optionally uploads results to Maya.

Format:

- process:
    video: <string>                    # Required
    upload:                             # Optional
      animation: <bool>                # Default: false
      audio: <bool>                    # Default: false
      frames: <bool>                   # Default: false
      lm_frames: <bool>                # Default: false
    export:                             # Optional
      scene: <bool>                    # Default: false
      playblast: <bool>                # Default: false
    force_reprocess: <bool>            # Optional, default: true
    time_offset_frames: <int>          # Optional, default: 0
    reopen_maya_scene: <bool>          # Optional, default: auto (see below)
    overrides:                          # Optional
      command_port: <int>              # Optional, override commandPort for this step
      maya_scene: <string>             # Optional, override maya_scene for this step
      maya_base: <string>              # Optional, override maya_base for this step
      out_scene_path: <string>        # Optional, path to save Maya scene file (.ma or .mb)
      out_playblast_path: <string>    # Optional, path to save playblast video

Fields:

video (required, string): Path to the video file to process
upload (optional, mapping): Upload options to Maya
- animation (bool): Upload animation curves
- audio (bool): Upload audio track
- frames (bool): Upload video frames as image sequence
- lm_frames (bool): Upload landmark-annotated frames. Not supported with ++ pipelines (RP++, Rich++, Robust++); raises LM_FRAMES_UNSUPPORTED_PIPELINE if used with one.
export (optional, mapping): Export options after processing
- scene (bool): Export Maya scene file
- playblast (bool): Export playblast video
force_reprocess (optional, bool): Force reprocessing even if cache exists. Default: true
time_offset_frames (optional, integer): Frame offset for animation upload. Default: 0, must be >= 0.
reopen_maya_scene (optional, bool): Controls whether the Maya scene is reopened before processing:
- true — always reopen, regardless of overrides or upload flags
- false — never reopen (explicit opt-out)
- omitted — auto: reopen only when any override (command_port, maya_scene, or maya_base) is present AND at least one upload.* flag is true
- Positive values: Animation starts at the time_offset_framesth frame on Maya
- Zero: No offset
overrides (optional, mapping): Override values for this specific process step
- command_port (optional, integer): Maya commandPort number to use for this step. Must be an integer between 1 and 65535. If provided, recreates the connection with the specified port for this step only, overriding the port from context.command_port or application settings. A preflight check is performed after to ensure Maya is reachable.
- maya_scene (optional, string): Path to Maya scene file to use for this step. Overrides the session’s maya_scene when reopen_maya_scene is true.
- maya_base (optional, string): Path to Maya workspace base directory to use for this step. Overrides the session’s maya_base when reopen_maya_scene is true.
- out_scene_path (optional, string): Path to save Maya scene file (must have .ma or .mb extension). If not provided when export.scene is true, a warning is logged and the scene is not saved.
- out_playblast_path (optional, string): Path to save playblast video, without a file extension (.mp4 is appended automatically). If not provided when export.playblast is true, a default path is derived from the session’s output folder and app settings.
Note: The process step always recreates the Affogato connection with the effective port (override or context) and performs a preflight check before processing. When reopen_maya_scene is omitted and overrides are present, the scene is reopened automatically (see reopen_maya_scene above).

Internal Maya Workflow
When any upload.* option is enabled in a process step, the CLI performs the following operations in Maya via commandPort, in strict sequence:

Scene timing setup

Set the Maya scene FPS to match the input video.
Set the scene playback range to match the total frame count of the video.

Audio setup (if upload.audio = true)

Import the audio track from the input video.
Attach the audio to the Maya timeline.

Reference frame setup (if upload.frames = true or upload.lm_frames = true)

Extract video frames as an image sequence.
Create or update an imagePlane using: raw frames if upload.frames = true landmark-annotated frames if upload.lm_frames = true

Animation reset

Remove all existing animation keyframes for every controller defined in the session.
This guarantees deterministic uploads and prevents keyframe accumulation across runs.

Animation upload

Apply newly computed animation curves to all session controllers.
If time_offset_frames > 0, all keyframes are shifted forward by the specified number of frames prior to insertion.

Output saving

Save the playblast video (if export.playblast = true).
Save the Maya scene file (if export.scene = true).

Notes

All operations are executed atomically per process step; partial uploads are not supported.

If reopen_maya_scene = true, the Maya scene is reopened before this workflow begins.

Controller matching is name-based. Controllers that cannot be resolved will silently receive no animation; no rollback is performed.

This workflow is executed only when at least one upload.* option is enabled. Processing without uploads does not modify the Maya scene.

Example:

- process:
    video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
    upload:
      animation: true
      audio: true
    export:
      scene: true
      playblast: true
    force_reprocess: true
    reopen_maya_scene: true
    time_offset_frames: 100
    overrides:
      command_port: 42070
      maya_scene: "D:/maya_scenes/alternate_scene.mb"
      maya_base: "D:/maya_workspace"
      out_scene_path: "D:/output/take_01.ma"
      out_playblast_path: "D:/output/take_01_playblast"

`sleep` Step

Pauses script execution for a specified duration. Useful for waiting between operations or allowing external processes to complete.

Format:

- sleep:
    seconds: <float>    # Required: number of seconds to sleep

Fields:

seconds (required, float): Number of seconds to pause execution. Must be a non-negative number.

Example:

- sleep:
    seconds: 5.0  # Wait 5 seconds

- sleep:
    seconds: 2.5  # Wait 2.5 seconds

Examples

Example 1: Basic Processing

Process a video and upload animation to Maya:

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true

Example 2: Multiple Videos with Scene Changes

Process multiple videos, changing Maya scene between them. Because maya_scene is overridden and upload.animation is true, the scene is reopened automatically:

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true
        audio: true
      overrides:
        maya_scene: "D:/maya_scenes/scene_01.mb"

  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_01_t00.mp4"
      upload:
        animation: true
      overrides:
        maya_scene: "D:/maya_scenes/scene_02.mb"

Example 3: Animation with Time Offset

Upload animations with different time offsets:

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true
      time_offset_frames: 100    # Starts at frame 100 in Maya

  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_01_t00.mp4"
      upload:
        animation: true
      time_offset_frames: 200    # Starts at frame 200 in Maya

Example 4: Controller Prefix Management

Add controller prefix in context before processing:

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"
  rename_controllers:
    prefix: "char_face_"
    action: "prepend"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true

Example 5: Full Processing Pipeline

Complete workflow with all features. Note: lm_frames requires a non-++ pipeline (e.g. Rich, Robust, RP), so the context sets pipeline: "Rich":

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"
  wait_seconds_after_scene_open: 2.0
  initial_scene_open: true
  command_port: 42069
  pipeline: "Rich"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true
        audio: true
        frames: true
        lm_frames: true
      export:
        scene: true
        playblast: true
      force_reprocess: true
      time_offset_frames: 0
      # reopen_maya_scene omitted — auto-reopens because overrides are present and upload is requested
      overrides:
        command_port: 42070
        maya_scene: "D:/maya_scenes/alternate_scene.mb"
        maya_base: "D:/maya_workspace"
        out_scene_path: "D:/output/take_01_processed.ma"
        out_playblast_path: "D:/output/take_01_playblast"

Example 6: Skip Initial Scene Opening

Disable the automatic scene open at startup, then explicitly reopen per-step:

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"
  initial_scene_open: false  # Skip initial scene opening after validation

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true
      reopen_maya_scene: true  # Explicitly reopen before this step

Example 7: Profile Selection

Disable all profiles then randomly enable 10 from a specific video:

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"
  profiles:
    - match: all
      select: none
    - match:
        - video: "ROM_walk"
      select: 10

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true

Logging

When a script is executed (not in --dry-run mode), the CLI automatically creates a log file next to the script at <script_name>.log. For example, running my_script.yaml produces my_script.log in the same directory.

Log level: INFO and above (INFO, WARNING, ERROR)
Encoding: UTF-8
Lifecycle: The log file is created when execution begins and the log sink is removed when execution completes (regardless of success or failure). If the log file already exists, it is overwritten.

This log file captures the same structured messages shown in the console output, providing a persistent record of script execution for debugging and auditing.

Error Handling

Error Codes

The CLI uses structured error codes for programmatic error handling:

Code	Description
`SESSION_NOT_FOUND`	Session file does not exist
`SESSION_INVALID`	Session file is invalid or corrupted
`SESSION_LOAD_ERROR`	Error loading session (generic load failure)
`NO_SESSION_LOADED`	Attempted operation without loading a session
`MISSING_RENAME_CONTROLLERS_PREFIX`	Missing prefix in `rename_controllers` context field
`INVALID_RENAME_CONTROLLERS_PREFIX`	Invalid prefix value in `rename_controllers` context field
`INVALID_RENAME_CONTROLLERS_ACTION`	Invalid action in `rename_controllers` context field (must be “prepend” or “remove”)
`PROFILES_INSUFFICIENT_MATCH`	`select: N` specified but fewer than N profiles matched the rule
`VIDEO_NOT_FOUND`	Video file does not exist
`MAYA_NOT_REACHABLE`	Maya commandPort is not reachable
`MAYA_SCENE_NOT_SET`	Maya scene path not set in session or overrides
`MAYA_SCENE_NOT_FOUND`	Maya scene file does not exist
`MAYA_SCENE_OPEN_ERROR`	Failed to open Maya scene (raised when `reopen_maya_scene` is `true`)
`MAYA_BASE_NOT_SET`	Maya base path not set in session
`MAYA_BASE_NOT_FOUND`	Maya base folder does not exist
`PIPELINE_ERROR`	Video processing pipeline failed (train/predict failure)
`ANIMATION_NOT_FOUND`	Animation cache file not found after processing
`LM_FRAMES_UNSUPPORTED_PIPELINE`	`lm_frames` upload requested with a `++` pipeline (not supported)
`DENOISING_PROFILE_NOT_FOUND`	Denoising profile file not found at specified path
`DENOISING_PROFILE_LOAD_ERROR`	Failed to load denoising profile file
`OUTPUT_DIR_NOT_CREATED`	Failed to create required output directory
`OUTPUT_FILE_NOT_CREATED`	Expected output file(s) were not created after processing
`PLAYBLAST_PATH_HAS_SUFFIX`	`out_playblast_path` was provided with a file extension (`.mp4` is appended automatically)

Execution Behavior

Validation Errors: Script validation fails before any steps are executed (exit code 1)
Maya Errors: Maya-related failures (not reachable, scene open failure, etc.) exit with code 2
Execution Errors: Script stops at the first failed step (exit code 3)

Exit Codes

0: Success
1: Validation error (script schema validation, missing fields, invalid values)
2: Maya related error (Maya not reachable, scene open failure, Maya configuration issues)
3: Execution failure (license check failed, session load error, pipeline error, step execution failure)

Maya Integration

Prerequisites

Maya must be running with commandPort enabled
CommandPort must be open (typically port 42069, or as specified in the script’s context.command_port)

Maya Preflight and Scene Opening

Before executing any steps, the CLI performs a preflight check:

Tests Maya commandPort connectivity
If Maya is not reachable:
- Logs error: MAYA_NOT_REACHABLE
- Exits with code 2
- No steps are executed
If Maya is reachable and initial_scene_open is true (the default):
- Automatically opens the Maya scene specified in the session (maya_scene and maya_base)
- Waits for wait_seconds_after_scene_open seconds if configured
- This ensures the scene is ready before processing begins

Upload Options

When processing videos, you can upload:

Animation: Facial animation curves (blendshapes, controllers)
Audio: Audio track from video
Frames: Video frames as image sequence for reference
LM Frames: Landmark-annotated frames for visualization

Scene Management

reopen_maya_scene: Controls when the Maya scene is reopened before a process step. true = always, false = never, omitted = auto (when any override is present and at least one upload flag is true). When reopening, override values for maya_scene/maya_base take precedence over session values.
overrides.out_scene_path: Saves the Maya scene to a specific path after processing
overrides.out_playblast_path: Saves a playblast video to a specific path after processing
Scene paths are resolved from the session’s maya_base and maya_scene properties
Process Step Preflight: Before each process step, a connection is recreated with the effective port (from override or context), and a preflight check is performed to ensure Maya is reachable

Time Offset

The time_offset_frames parameter allows you to control where animation starts on the Maya timeline:

Positive offset: Animation starts later (e.g., 100 starts at frame 100)
Zero: Animation starts at the default position (typically frame 0)
Note: Only non-negative values (>= 0) are allowed

This is useful for:

Combining multiple takes in a single timeline
Aligning animation with existing keyframes
Creating animation sequences with gaps

Troubleshooting

Script Validation Fails

Problem: Script fails validation with error about structure or types.

Solutions:

Ensure version: 1 is present and exactly 1
Check that context.session is a non-empty string
Verify steps is a non-empty list
Ensure each step has exactly one key (process or sleep)
Check field types match the schema (strings, booleans, integers)

Maya Not Reachable

Problem: Script exits with MAYA_NOT_REACHABLE error.

Solutions:

Ensure Maya is running
Verify commandPort is open: In Maya, run cmds.commandPort(n=':42069', stp='python') (or use the port specified in context.command_port if provided)
Verify firewall/network settings allow localhost connections
If using a custom command_port in context, ensure Maya’s commandPort matches the specified port number

Video Processing Fails

Problem: PIPELINE_ERROR during video processing.

Solutions:

Verify video file exists and is readable
Check session has valid solver configuration
Ensure sufficient disk space for cache
Review logs for detailed error messages

Animation Not Uploading

Problem: Animation upload appears to succeed but nothing appears in Maya.

Solutions:

Verify Maya scene has the correct character rig loaded
Check controller names match between session and Maya scene
Ensure animation layer exists in Maya (default: “BaseAnimation”)
Review Maya script editor for Python errors

Best Practices

Always validate first: Use --dry-run to validate scripts before execution
Use explicit paths: Prefer absolute paths for reliability
Test incrementally: Start with simple scripts, add complexity gradually
Check Maya connection: Ensure Maya is running before processing with upload
Use time offsets carefully: Verify frame ranges to avoid overlaps
Version control scripts: Keep scripts in version control for repeatability

Advanced Usage

Batch Processing

Process multiple videos in sequence:

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true
      time_offset_frames: 0

  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_01_t00.mp4"
      upload:
        animation: true
      time_offset_frames: 1000

  - process:
      video: "D:/shots/take_03.mp4"
      upload:
        animation: true
      time_offset_frames: 2000

Controller Prefix Management

Add controller prefix in context before processing:

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"
  rename_controllers:
    prefix: "char_face_"
    action: "prepend"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true

Conditional Scene Switching

Change Maya scene per step. Scene is reopened automatically because maya_scene is overridden and upload is requested:

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"

steps:
  - process:
      video: "D:/shots/closeup_01.mp4"
      upload:
        animation: true
      overrides:
        maya_scene: "D:/maya_scenes/closeup_scene.mb"

  - process:
      video: "D:/shots/wide_01.mp4"
      upload:
        animation: true
      overrides:
        maya_scene: "D:/maya_scenes/wide_scene.mb"

Support

For issues, questions, or feature requests, please refer to the main FCS documentation or contact the development team.

CLI Tool

Table of Contents

Installation

Quick Start

Script Format

Top-Level Structure

Version

Context

Steps

Validation Strictness

Profiles

Execution Model

Execution Lifecycle

Context and Overrides

Execution Guarantees

Commands

Run Script

Step Types

process Step

sleep Step

Examples

Example 1: Basic Processing

Example 2: Multiple Videos with Scene Changes

Example 3: Animation with Time Offset

Example 4: Controller Prefix Management

Example 5: Full Processing Pipeline

Example 6: Skip Initial Scene Opening

Example 7: Profile Selection

Logging

Error Handling

Error Codes

Execution Behavior

Exit Codes

Maya Integration

Prerequisites

Maya Preflight and Scene Opening

Upload Options

Scene Management

Time Offset

Troubleshooting

Script Validation Fails

Maya Not Reachable

Video Processing Fails

Animation Not Uploading

Best Practices

Advanced Usage

Batch Processing

Controller Prefix Management

Conditional Scene Switching

Support

`process` Step

`sleep` Step