chuansuo 0.1.0

Make videos seamlessly loopable by reordering frames

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
• 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

功能

• 提取偶数帧并逆序追加，生成无缝循环视频
• 按视觉相似度排序帧，实现平滑过渡
• 音频处理选项：与视频同步重排、保持原音、或交叉淡入淡出平滑
• 输出视频始终回到第一帧，实现完美循环播放
• 统一命令行参数（-V、-v、-o、--json、-q）
• Python API 支持 ToolResult 模式
• OpenAI 函数调用集成

Requirements

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

依赖

• Python 3.10+
• opencv-python >= 4.8.0
• numpy >= 1.24.0
• pydub >= 0.25.0
• ffmpeg（系统依赖，用于音频处理）

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

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.

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] 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

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