Skip to content

Commit 4cb70f5

Browse files
tiehongjitiehongji
authored
Merge pull request #12 from volcengine/feat/opt-doc
Feat/opt doc
2 parents 56ec901 + 1901424 commit 4cb70f5

18 files changed

Lines changed: 729 additions & 320 deletions

File tree

‎.goreleaser.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,10 @@ archives:
4747
checksum:
4848
name_template: checksums.txt
4949

50+
release:
51+
prerelease: auto
52+
make_latest: "{{ if .Prerelease }}false{{ else }}true{{ end }}"
53+
5054
snapshot:
5155
version_template: "{{ incpatch .Version }}-snapshot"
5256

‎README.en.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# AI MediaKit CLI
2+
3+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4+
[![Go Version](https://img.shields.io/badge/go-%3E%3D1.22-blue.svg)](https://go.dev/)
5+
[![npm version](https://img.shields.io/npm/v/@volcengine/mediakit-cli.svg)](https://www.npmjs.com/package/@volcengine/mediakit-cli)
6+
7+
[中文版](./README.md) | [English](./README.en.md)
8+
9+
The official Mediakit CLI — an FFmpeg-compatible command surface. The same command can run FFmpeg locally for editing operations such as trimming, concatenation, subtitling, mixing, and audio extraction, or switch to the cloud with a single flag to invoke AI capabilities that FFmpeg cannot deliver — quality enhancement, subtitle erasure, ASR, OCR, storyline analysis, and more. It already covers atomic capabilities across video, image, and audio modalities plus 5 AI Agent [Skills](./skills/), with 100+ audio/video atomic capabilities planned.
10+
11+
[Installation](#installation--quick-start) · [AI Agent Skills](#agent-skills) · [Authentication](#authentication) · [Command Structure](#command-structure) · [Advanced Usage](#advanced-usage) · [License](#license)
12+
13+
## Why choose mediakit-cli?
14+
15+
- **Comprehensive capability matrix**: spans video, image, and audio modalities, from low-level processing such as trimming / concatenation / subtitling to high-level understanding such as quality enhancement, subtitle erasure, ASR, OCR, and storyline analysis — a single command covers the full pipeline from preprocessing to final output.
16+
- **FFmpeg-compatible, seamless migration**: local mode is built on `ffmpeg` / `ffprobe`, covering common capabilities such as trimming, concatenation, image overlay, subtitle overlay, speed adjustment, volume adjustment, flipping, fade in/out, mixing, audio/video composition, audio extraction, green-screen keying, and metadata probing — aligned with FFmpeg command intuition. Complex / AI capabilities such as filters, image-to-video, and concatenation transitions are handled in the cloud.
17+
- **Cloud is faster and more powerful**: append `--cloud` to the same command to unlock capabilities FFmpeg cannot deliver — quality enhancement / generative quality restoration, subtitle erasure (standard / fine-grained), ASR, video OCR, highlight clipping (short drama / mini-game), storyline analysis, scene segmentation, green-screen / portrait keying, and other AI atomic capabilities. Cloud elastic compute provides second-level concurrency.
18+
- **One command, two modes**: `--local` / `--cloud` can be switched per command; local mode is zero-cost and cloud provides elastic compute, complementing each other. They share the same parameters and `--schema`, so Agents / scripts can switch with zero modification.
19+
- **Cost-effective processing**: leverages cloud elastic resource scheduling and off-peak batch processing strategies to provide highly competitive pricing for large batches of media tasks, significantly reducing overall token consumption and operational cost for AI applications.
20+
21+
## Features
22+
23+
| Domain | Capabilities | Runtime |
24+
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
25+
| 🎬 **Editing** (17) | Video trim · Audio trim · Video concat · Audio concat · Video image overlay · Video subtitle overlay · Video speed · Audio speed · Video volume adjust · Video filter · Video flip · Video audio fade in/out · Audio fade in/out · Audio mix · Video + audio · Extract audio · Image to video | Cloud **or** Local |
26+
| 🎚️ **Audio** (2) | Voice / background separation · Audio metadata | Cloud |
27+
| 🖼️ **Image AI** (5) | Image quality enhancement · Image erase & inpaint · Image quality assessment · Image OCR · Image background removal | Cloud |
28+
| 🎥 **Video AI** (14) | Quality enhancement · Generative quality enhancement · Subtitle erasure (standard) · Fine-grained subtitle erasure · Speech-to-subtitles (ASR) · Video subtitle OCR · Highlight clipping - short drama · Highlight clipping - mini-game · Highlight extraction · Storyline analysis · Scene segmentation · Video green-screen keying · Video portrait keying · Video metadata | Cloud |
29+
| 🔧 **Common** (2) | Async task query · Remote file fetch | Local / Cloud |
30+
| 🚧 **Coming soon** | Video translation · Narration generation · Manga-to-animation (rolling out) | Cloud |
31+
32+
## Installation & Quick Start
33+
34+
### Requirements
35+
36+
Before you begin, make sure you have:
37+
38+
- Node.js `>=18` (`npm` / `npx`)
39+
40+
- Local mode: `ffmpeg` `5.1.x` and `ffprobe`
41+
42+
### Quick Start (Human Users)
43+
44+
#### Installation
45+
46+
Choose **one** of the following methods:
47+
48+
**Option 1 — one-click install:**
49+
50+
```bash
51+
npx @volcengine/mediakit-cli install -y
52+
```
53+
54+
**Option 2 — build from source:**
55+
56+
Requires Go `v1.22`+.
57+
58+
```bash
59+
git clone https://github.com/volcengine/mediakit-cli.git
60+
cd mediakit-cli
61+
make build # Artifact: .mediakit/build/dev/mediakit-cli
62+
63+
# Install AI Agent Skills from local skills directory (required)
64+
npx -y skills add ./skills -g -y
65+
```
66+
67+
#### Configuration & Usage
68+
69+
```bash
70+
# 1. Initialize configuration (interactive wizard)
71+
mediakit-cli init
72+
73+
# 2. Environment self-check (cloud connectivity, local dependencies, install suggestions)
74+
mediakit-cli doctor
75+
76+
# 3. Local editing (synchronous, no API Key needed): run FFmpeg locally to trim
77+
mediakit-cli --local editing trim-video --video-url ./in.mp4 --start-time 3 --end-time 8
78+
79+
# 4. Cloud AI (async): enhance a video to 1080p, then poll for the final result
80+
mediakit-cli --cloud video enhance-video --video-url <url> --resolution 1080p
81+
mediakit-cli shared query-task --task-id <task_id> --poll-complete
82+
```
83+
84+
### Quick Start (AI Agent)
85+
86+
> The following steps are designed for AI Agents and support fully unattended workflows.
87+
88+
**Step 1 — Install**
89+
90+
```bash
91+
npx @volcengine/mediakit-cli install -y
92+
```
93+
94+
**Step 2 — Non-interactive initialization (`--yes` mode)**
95+
96+
```bash
97+
# Get an API Key at: https://console.volcengine.com/imp/ai-mediakit/settings
98+
mediakit-cli init \
99+
--mode cloud-first \
100+
--api-key <your-api-key> \
101+
--yes
102+
```
103+
104+
**Step 3 — Verify**
105+
106+
```bash
107+
mediakit-cli doctor
108+
mediakit-cli version
109+
```
110+
111+
## Agent Skills
112+
113+
| Skill | Description |
114+
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
115+
| `byted-mediakit-shared` | Common capabilities: task query — required by all other skills |
116+
| `byted-mediakit-editing` | Editing: video trim, audio trim, video concat, audio concat, video image overlay, video subtitle overlay, video speed, audio speed, video volume adjust, video filter, video flip, video audio fade in/out, audio fade in/out, audio mix, video + audio, extract audio, image to video |
117+
| `byted-mediakit-audio` | Audio: voice / background separation, audio metadata |
118+
| `byted-mediakit-image` | Image AI: image quality enhancement, image erase & inpaint, image quality assessment, image OCR, image background removal |
119+
| `byted-mediakit-video` | Video AI: quality enhancement, generative quality enhancement, subtitle erasure (standard), fine-grained subtitle erasure, speech-to-subtitles (ASR), video subtitle OCR, highlight clipping - short drama, highlight clipping - mini-game, highlight extraction, storyline analysis, scene segmentation, video green-screen keying, video portrait keying, video metadata |
120+
121+
## Authentication
122+
123+
`mediakit-cli` uses minimal authentication: just an API Key — no OAuth / STS / IAM role configuration required.
124+
125+
```bash
126+
# Option A: choose a storage method during init (config / shell / export)
127+
mediakit-cli init --api-key <your-api-key> --credential-store config --yes
128+
129+
# Option B: inject temporarily via environment variables
130+
export MEDIAKIT_API_KEY=<your-api-key>
131+
export MEDIAKIT_OUTPUT_PATH=<optional-custom-endpoint>
132+
```
133+
134+
| Environment variable | Description |
135+
| ---------------------- | -------------------------------------------------------------------------------------------------- |
136+
| `MEDIAKIT_API_KEY` | Cloud API Key ([get it from the console](https://console.volcengine.com/imp/ai-mediakit/settings)) |
137+
| `MEDIAKIT_OUTPUT_PATH` | Local mode output directory, defaults to `~/.mediakit/temp` |
138+
139+
## Command Structure
140+
141+
```
142+
mediakit-cli [--cloud|--local] <domain> <tool> [flags]
143+
```
144+
145+
- **Two modes, one command surface**: `--cloud` uses cloud elastic compute (asynchronously returns a `task_id`); `--local` uses local FFmpeg (synchronous, zero cost). Default is `cloud-first`, and it can be overridden per command with `--cloud` / `--local`.
146+
- **Output**: cloud results are returned as URLs; local results land in `~/.mediakit/temp` (override with `--output-path` or `MEDIAKIT_OUTPUT_PATH`).
147+
148+
System commands:
149+
150+
| Command | Description |
151+
| -------------------------------------------- | ------------------------------------------------------------------------------------------- |
152+
| `mediakit-cli init [--yes]` | Initialize configuration, interactive or non-interactive (Agent-friendly) |
153+
| `mediakit-cli doctor` | Check cloud connectivity, local dependencies, and install suggestions |
154+
| `mediakit-cli config` | View / modify configuration |
155+
| `mediakit-cli version [--check]` | Show version; `--check` compares against the latest npm release |
156+
| `mediakit-cli update [--check]` | Update the CLI and Skills via `npm install -g`; `--check` only checks without installing |
157+
| `mediakit-cli --domains` | List all domains |
158+
| `mediakit-cli --help-full` | List the full capability index |
159+
| `mediakit-cli <domain> <tool> --schema` | Output the JSON Schema for the capability (Mode / Async / polling command metadata) |
160+
| `mediakit-cli shared query-task --task-id X` | Query an async task; add `--poll-complete` to poll until terminal state |
161+
162+
## Advanced Usage
163+
164+
### Schema Introspection
165+
166+
Every capability command supports `--schema`, which outputs the input / output schema plus Mode and Async information for Agents to discover tool capabilities dynamically:
167+
168+
```bash
169+
mediakit-cli video enhance-video --schema
170+
mediakit-cli --local editing trim-video --schema
171+
```
172+
173+
### Local Mode Output Naming
174+
175+
Local mode output files are named by the following priority:
176+
177+
1. Explicit `--output-path` with a complete file path (including extension) → used directly
178+
2. Input filename available → `{original_filename}_{tool_name}.{ext}`; if a file with the same name already exists, a 6-digit random number is appended
179+
3. No input filename → `{tool_name}-{timestamp}.{ext}`
180+
181+
## License
182+
183+
This project is open-sourced under the **MIT License**.
184+
185+
At runtime this software calls MediaKit cloud APIs. Using those APIs is subject to the following agreements:
186+
187+
- [Video Cloud Services Specific Terms](https://www.volcengine.com/docs/6448/79646?lang=zh)
188+
- [Intelligent Processing Service Billing Rules](https://www.volcengine.com/docs/6448/104992?lang=zh)
189+
- [Intelligent Processing Service SLA](https://www.volcengine.com/docs/6448/79648?lang=zh)

0 commit comments

Comments
 (0)