Skip to content

Commit a553a60

Browse files
sohei-tsohei-t
committed
docs: add comprehensive English README with detailed project documentation
1 parent fe7f418 commit a553a60

1 file changed

Lines changed: 212 additions & 45 deletions

File tree

‎README.md‎

Lines changed: 212 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,258 @@
11
# Python Video Tools
22

33
[![CI](https://github.com/sohei-t/python-video-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/sohei-t/python-video-tools/actions/workflows/ci.yml)
4-
[![Python](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)
4+
[![Python](https://img.shields.io/badge/Python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-3776AB?logo=python&logoColor=white)](https://www.python.org/)
55
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
66

7-
動画・画像編集用のPythonツール集。ffmpegやOpenCVを活用した、CLIで簡単に使えるツールを提供します。
7+
A comprehensive collection of 11 modular command-line utilities for video, audio, and image processing. Each tool is self-contained with its own dependencies and documentation, built on top of ffmpeg, OpenCV, and other established multimedia libraries.
88

9-
## ツール一覧
9+
---
1010

11-
### 動画処理
11+
## Table of Contents
1212

13-
| ツール | 説明 |
14-
|-------|------|
15-
| [video-segment-tools](./video-segment-tools/) | 動画の切り出し・分割・結合 |
16-
| [video-grid-composer](./video-grid-composer/) | 複数動画の横並び・縦並び・グリッド結合 |
17-
| [video-compressor](./video-compressor/) | 動画ファイルサイズ縮小 |
18-
| [video-speed-changer](./video-speed-changer/) | 再生速度・フレームレート変更 |
19-
| [video-overlay](./video-overlay/) | 画像・動画のオーバーレイ合成 |
20-
| [video-player](./video-player/) | Webブラウザベースの動画プレイヤー |
13+
- [Overview](#overview)
14+
- [Tools](#tools)
15+
- [Tech Stack](#tech-stack)
16+
- [Prerequisites](#prerequisites)
17+
- [Installation](#installation)
18+
- [Usage Examples](#usage-examples)
19+
- [Testing](#testing)
20+
- [Contributing](#contributing)
21+
- [License](#license)
2122

22-
### 音声処理
23+
---
2324

24-
| ツール | 説明 |
25-
|-------|------|
26-
| [audio-extractor](./audio-extractor/) | 動画から音声をMP3に抽出 |
27-
| [audio-remover](./audio-remover/) | 動画から音声トラックを除去 |
25+
## Overview
2826

29-
### 画像処理
27+
Python Video Tools provides a toolkit of focused, single-purpose CLI utilities for common multimedia processing tasks. Rather than a monolithic application, each tool is an independent module that can be used in isolation or combined in shell pipelines for complex workflows.
3028

31-
| ツール | 説明 |
32-
|-------|------|
33-
| [face-cropper](./face-cropper/) | 顔検出・切り出し＆スライドショー作成 |
34-
| [frame-extractor](./frame-extractor/) | 動画から指定間隔で静止画抽出 |
35-
| [image-combiner](./image-combiner/) | 複数画像を横並び・縦並びで結合 |
29+
Key design principles:
3630

37-
## インストール
31+
- **Modular** -- Each tool is self-contained in its own directory with dedicated dependencies
32+
- **CLI-first** -- All tools are invoked from the command line with clear argument interfaces
33+
- **Batch-capable** -- Tools support processing multiple files in a single invocation
34+
- **Cross-platform** -- Compatible with macOS, Linux, and Windows (where dependencies are available)
35+
36+
---
37+
38+
## Tools
39+
40+
### Video Processing
41+
42+
| Tool | Description | Key Dependencies |
43+
|------|-------------|------------------|
44+
| [video-segment-tools](./video-segment-tools/) | Extract, split, and merge video segments by timestamp | ffmpeg |
45+
| [video-grid-composer](./video-grid-composer/) | Compose multiple videos into side-by-side, stacked, or grid layouts | ffmpeg |
46+
| [video-compressor](./video-compressor/) | Reduce video file size with configurable quality presets | ffmpeg |
47+
| [video-speed-changer](./video-speed-changer/) | Adjust playback speed and frame rate | ffmpeg |
48+
| [video-overlay](./video-overlay/) | Overlay images or videos onto a base video | moviepy |
49+
| [video-player](./video-player/) | Browser-based video player with a Flask backend | Flask |
50+
51+
### Audio Processing
52+
53+
| Tool | Description | Key Dependencies |
54+
|------|-------------|------------------|
55+
| [audio-extractor](./audio-extractor/) | Extract audio tracks from video files as MP3 | ffmpeg |
56+
| [audio-remover](./audio-remover/) | Strip audio tracks from video files | ffmpeg |
57+
58+
### Image Processing
59+
60+
| Tool | Description | Key Dependencies |
61+
|------|-------------|------------------|
62+
| [face-cropper](./face-cropper/) | Detect and crop faces from images, generate slideshows | dlib, OpenCV |
63+
| [frame-extractor](./frame-extractor/) | Extract still frames from video at specified intervals | OpenCV |
64+
| [image-combiner](./image-combiner/) | Combine multiple images in horizontal, vertical, or grid layouts | Pillow |
65+
66+
---
67+
68+
## Tech Stack
69+
70+
| Technology | Version | Role |
71+
|-----------|---------|------|
72+
| Python | 3.9+ | Runtime |
73+
| ffmpeg | Latest | Video/audio encoding and manipulation |
74+
| OpenCV | 4.x | Computer vision and frame extraction |
75+
| moviepy | 1.x | Video compositing and overlay |
76+
| dlib | Latest | Face detection |
77+
| Pillow (PIL) | Latest | Image manipulation |
78+
| NumPy | Latest | Numerical operations for image processing |
79+
| Flask | Latest | Web-based video player backend |
80+
81+
---
82+
83+
## Prerequisites
84+
85+
### Python
86+
87+
Python 3.9 or later is required. Verify your installation:
88+
89+
```bash
90+
python3 --version
91+
```
92+
93+
### ffmpeg
94+
95+
Most tools depend on ffmpeg for video and audio processing.
96+
97+
**macOS:**
98+
99+
```bash
100+
brew install ffmpeg
101+
```
102+
103+
**Ubuntu / Debian:**
104+
105+
```bash
106+
sudo apt install ffmpeg
107+
```
108+
109+
**Windows:**
110+
111+
Download from [ffmpeg.org](https://ffmpeg.org/download.html) and add to your system PATH.
112+
113+
### dlib (for face-cropper only)
114+
115+
The face-cropper tool requires dlib, which may need CMake for compilation:
116+
117+
**macOS:**
118+
119+
```bash
120+
brew install cmake
121+
pip install dlib
122+
```
123+
124+
**Ubuntu / Debian:**
125+
126+
```bash
127+
sudo apt install cmake libboost-all-dev
128+
pip install dlib
129+
```
130+
131+
---
132+
133+
## Installation
38134

39135
```bash
40136
git clone https://github.com/sohei-t/python-video-tools.git
41137
cd python-video-tools
42138
```
43139

44-
各ツールのディレクトリに移動して、必要な依存関係をインストールしてください。
140+
Each tool manages its own dependencies. Install them per-tool as needed:
45141

46-
## 必要条件
142+
```bash
143+
# Example: install dependencies for the face-cropper tool
144+
cd face-cropper
145+
pip install -r requirements.txt
146+
```
47147

48-
- Python 3.9+
49-
- ffmpeg（動画処理ツール用）
50-
- OpenCV, NumPy（画像・動画処理用）
51-
- dlib（顔検出用）
52-
- Pillow（画像処理用）
53-
- moviepy（動画オーバーレイ用）
54-
- Flask（動画プレイヤー用）
148+
Or install common dependencies for all tools:
55149

56-
### ffmpegのインストール
150+
```bash
151+
pip install opencv-python numpy pillow moviepy flask dlib
152+
```
153+
154+
---
155+
156+
## Usage Examples
157+
158+
### Extract audio from a video file
57159

58-
**macOS:**
59160
```bash
60-
brew install ffmpeg
161+
cd audio-extractor
162+
python audio_extractor.py input.mp4 -o output.mp3
163+
```
164+
165+
### Compress a video to reduce file size
166+
167+
```bash
168+
cd video-compressor
169+
python video_compressor.py input.mp4 -o compressed.mp4 --quality medium
61170
```
62171

63-
**Ubuntu/Debian:**
172+
### Create a 2x2 grid from four videos
173+
64174
```bash
65-
sudo apt install ffmpeg
175+
cd video-grid-composer
176+
python video_grid_composer.py video1.mp4 video2.mp4 video3.mp4 video4.mp4 -o grid.mp4 --layout 2x2
177+
```
178+
179+
### Extract frames every 5 seconds
180+
181+
```bash
182+
cd frame-extractor
183+
python frame_extractor.py input.mp4 -o frames/ --interval 5
184+
```
185+
186+
### Detect and crop faces from an image
187+
188+
```bash
189+
cd face-cropper
190+
python face_cropper.py photo.jpg -o faces/
191+
```
192+
193+
### Change video playback speed
194+
195+
```bash
196+
cd video-speed-changer
197+
python video_speed_changer.py input.mp4 -o fast.mp4 --speed 2.0
198+
```
199+
200+
### Combine images side by side
201+
202+
```bash
203+
cd image-combiner
204+
python image_combiner.py img1.png img2.png -o combined.png --direction horizontal
205+
```
206+
207+
### Remove audio from a video
208+
209+
```bash
210+
cd audio-remover
211+
python audio_remover.py input.mp4 -o silent.mp4
66212
```
67213

68-
## 開発
214+
---
69215

70-
### テストの実行
216+
## Testing
217+
218+
The project uses pytest for automated testing:
71219

72220
```bash
221+
# Install test dependencies
73222
pip install pytest pillow
223+
224+
# Run all tests
74225
pytest tests/ -v
75226
```
76227

77-
### コードフォーマット
228+
Tests are located in the `tests/` directory and cover core functionality for each tool.
229+
230+
---
231+
232+
## Contributing
233+
234+
Contributions are welcome. To add a new tool or improve an existing one:
235+
236+
1. Fork the repository
237+
2. Create a feature branch: `git checkout -b feature/my-new-tool`
238+
3. Add your tool in a new directory with its own `README.md` and `requirements.txt`
239+
4. Add tests in the `tests/` directory
240+
5. Ensure code passes formatting checks:
78241

79242
```bash
80243
pip install black isort
81244
black .
82245
isort .
83246
```
84247

85-
## ライセンス
248+
6. Open a pull request
249+
250+
---
251+
252+
## License
86253

87-
MIT License
254+
MIT License. See [LICENSE](./LICENSE) for details.
88255

89-
## 作者
256+
---
90257

91-
[@sohei-t](https://github.com/sohei-t)
258+
**Author:** [@sohei-t](https://github.com/sohei-t)

0 commit comments

Comments
 (0)