ChuanSuo (穿梭)

Make videos seamlessly loopable by reordering frames.

Features

• Extract even-indexed frames, reverse them, and append to create a seamless loop
• Sort frames by visual similarity for smooth transitions
• Audio handling options: reorder with video, keep original, or apply crossfade smoothing
• Lossless compression: Multiple strategies (delta, sparse, spatial, combined) with TSP reordering
• The output video always ends at frame 0, enabling perfect looping
• CLI with unified flags (-V, -v, -o, --json, -q)
• Python API with ToolResult pattern
• OpenAI function-calling integration

Requirements

• Python 3.10+
• opencv-python >= 4.8.0
• numpy >= 1.24.0
• pydub >= 0.25.0
• ffmpeg (system dependency for audio processing)

Installation

pip install -e .

Quick Start

# Make a video loopable
chuansuo input.mp4 -o output.mp4

# Verbose mode
chuansuo input.mp4 -o output.mp4 -v

# JSON output
chuansuo input.mp4 -o output.mp4 --json

Usage

Algorithm

Loop Mode

Given frames [0, 1, 2, 3, ..., N-1]:

1. Split into odd-indexed frames: [1, 3, 5, ...]
2. Split into even-indexed frames: [0, 2, 4, ...]
3. Output: odd frames + reversed even frames

Example with 10 frames: [1, 3, 5, 7, 9, 8, 6, 4, 2, 0]

The video ends at frame 0, enabling seamless looping back to 1. Total frame count and duration are unchanged - only the order is rearranged.

Compress Mode

1. Greedy TSP reordering: Frames are reordered using a greedy traveling salesman algorithm to minimize inter-frame pixel differences (entropy increase)
2. Delta encoding: First frame stored as key frame (PNG lossless), subsequent frames store only changed pixels with zlib compression
3. Lossless verification: Frames are reconstructed from deltas and verified pixel-perfect before output

Compression ratio depends on video content:

• Static scenes: 5-15% of original raw size
• Moderate motion: 20-40% of original raw size
• High motion: 40-60% of original raw size

Audio is processed identically: split into frame-aligned segments, reordered using the same pattern, and merged back with the video to maintain perfect A/V sync.

CLI

usage: chuansuo [-h] [-V] [-v] [-o OUTPUT] [--json] [-q] [-m MODE] input

Make videos seamlessly loopable by reordering frames

positional arguments:
  input                 Input video file path

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -v, --verbose         Enable verbose output
  -o OUTPUT, --output OUTPUT
                        Output video path (default: input_loop.mp4)
  --json                Output result as JSON
  -q, --quiet           Suppress non-essential output
  -m MODE, --mode MODE  Processing mode: loop, similarity, compress, or compare
  --smooth-audio        Apply crossfade between audio segments
  --audio-fade-ms MS    Crossfade duration in milliseconds (default: 50)
  --keep-audio          Keep original audio track unchanged

Python API

from chuansuo import chuansuo_make_loop

result = chuansuo_make_loop(
    input_path="input.mp4",
    output_path="output.mp4",
    verbose=True,
)
print(result.success)    # True / False
print(result.data)       # Processing metadata
print(result.metadata)   # Metadata including version

Agent Integration

from chuansuo.tools import TOOLS, dispatch

# TOOLS contains the OpenAI function-calling schema
# dispatch() routes tool calls to the appropriate API function
result = dispatch("chuansuo_make_loop", {"input_path": "video.mp4"})

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff format . && ruff check .

License

GPL-3.0