Metadata-Version: 2.4
Name: chuansuo
Version: 0.1.2
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
- **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

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

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

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