Metadata-Version: 2.4
Name: chuansuo
Version: 0.1.0
Summary: Make videos seamlessly loopable by reordering frames
License: GPL-3.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydub>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install -e .
```

## Quick Start

```bash
# 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

```python
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

```python
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

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

# Run tests
pytest tests/ -v

# Lint
ruff format . && ruff check .
```

## License

GPL-3.0
