@telepat/rilo 0.1.0 → 0.1.7

package/README.md

@@ -1,209 +1,100 @@
-# Rilo
-
-[![CI](https://github.com/telepat-io/rilo/actions/workflows/ci.yml/badge.svg)](https://github.com/telepat-io/rilo/actions/workflows/ci.yml)
-[![Coverage](https://codecov.io/gh/telepat-io/rilo/graph/badge.svg)](https://codecov.io/gh/telepat-io/rilo)
-[![npm version](https://img.shields.io/npm/v/%40telepat%2Frilo)](https://www.npmjs.com/package/@telepat/rilo)
-[![npm downloads](https://img.shields.io/npm/dm/%40telepat%2Frilo)](https://www.npmjs.com/package/@telepat/rilo)
-[![Docs](https://img.shields.io/badge/docs-live-22c55e)](https://docs.telepat.io/rilo/)
-[![License](https://img.shields.io/github/license/telepat-io/rilo)](./LICENSE)
-
-Story-first vertical video generation.
-
-Rilo turns one story into a complete short-form video pipeline:
-- script generation
-- voiceover generation
-- keyframe generation
-- video segment generation
-- final composition
-- optional subtitle alignment and burn-in
-
-## Why Rilo
-
-- Built for vertical video workflows
-- Checkpointed runs with resume support
-- Targeted regeneration for faster iteration
-- Model selection and per-model option overrides
-- Local and Firebase output backends
-- API, worker, and frontend flow for production usage
+<p align="center"><img src="./assets/avatar/rilo-logo.webp" width="128" alt="Rilo"></p>
+<h1 align="center">Rilo</h1>
+<p align="center"><em>Turn a story into a finished video — AI-generated script, voiceover, keyframes, and composition, all in one command.</em></p>
 
-## Quick Start
-
-Requirements:
-- Node.js 22+
-- ffmpeg in PATH
-- Replicate API token
-
-Setup:
-
-```bash
-npm install
-cp .env.example .env
-```
-
-Set required environment variables in .env, **or use the interactive settings command** (see below):
-
-```bash
-RILO_REPLICATE_API_TOKEN=your-token
-RILO_API_BEARER_TOKEN=your-api-bearer-token
-```
-
-Run the full local stack:
-
-```bash
-npm run dev:all
-```
-
-Run a CLI generation:
+<p align="center">
+  <a href="https://docs.telepat.io/rilo">📖 Docs</a>
+  · <a href="./README.md">🇺🇸 English</a>
+  · <a href="./README.zh-CN.md">🇨🇳 简体中文</a>
+</p>
 
-```bash
-rilo --project demo --story-file ./story.txt
-```
-
-## Settings
-
-Configure rilo interactively without editing files:
-
-```bash
-rilo settings
-```
+<p align="center">
+  <a href="https://github.com/telepat-io/rilo/actions/workflows/ci.yml"><img src="https://github.com/telepat-io/rilo/actions/workflows/ci.yml/badge.svg?branch=main" alt="Build"></a>
+  <a href="https://codecov.io/gh/telepat-io/rilo"><img src="https://codecov.io/gh/telepat-io/rilo/graph/badge.svg" alt="Codecov"></a>
+  <a href="https://www.npmjs.com/package/@telepat/rilo"><img src="https://img.shields.io/npm/v/@telepat/rilo" alt="npm"></a>
+  <a href="https://github.com/telepat-io/rilo/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="License"></a>
+</p>
 
-For local development in this repository:
+Rilo turns a story into a finished video — AI-generated script, voiceover, keyframes, and composition, all in one command.
 
-```bash
-npm run dev -- settings
-npm run dev -- --project demo --story-file ./story.txt
-```
-
-This opens a menu where you can edit all non-sensitive settings and manage API tokens securely. Navigate with arrow keys, select with Enter, and use "Done" or "Cancel" to exit. You can also press Ctrl+C at any time to quit.
+Write your story in plain text. Rilo handles the rest: script generation, narration, visual keyframes, video segments, and final composition — with optional subtitle alignment and burn-in.
 
-**What gets stored where:**
+Built for creators and teams who need reproducible, high-quality video at scale without manual editing.
 
-| Setting type | Storage |
-|---|---|
-| Replicate API Token, API Bearer Token | OS keystore (macOS Keychain, Windows Credential Manager, Linux Secret Service) — or an AES-256 encrypted file at `~/.rilo/.secrets` if no native keystore is available |
-| All other settings (timeouts, limits, binary paths, etc.) | `~/.rilo/config.json` |
+## Features
 
-**Precedence** (highest → lowest): environment variable > `~/.rilo/config.json` > schema default.  
-If an env var is set, the settings command shows it as read-only and any stored value is ignored while the env var is present.
+- **Full pipeline, one command** — Story → script → voiceover → keyframes → segments → final video. `rilo --project demo --story-file ./story.txt`
+- **Checkpointed runs** — Every stage saves artifacts. Resume or regenerate any stage selectively. `rilo --project demo --force`
+- **Your models, your control** — Choose T2I and I2V models. Override per-model options. Switch models anytime.
+- **Code-driven pipeline** — Deterministic orchestration, checkpointing, and artifact management. Tokens spent on generation, not infrastructure.
+- **Subtitle alignment & burn-in** — Auto-align subtitles to voiceover timing. Burn them into the final video.
+- **Preview dashboard** — Web UI for project management, regeneration, and asset preview. `rilo preview`
+- **HTTP API & webhooks** — Bearer-token auth, OpenAPI 3.1 spec, webhook subscriptions. Firebase or local.
+- **Cross-platform** — macOS, Linux, Windows. Node.js 22+ and ffmpeg.
 
-**Hidden from settings UI** (env-only): Firebase credentials, webhook settings, output backend, API port, custom output/projects directories.
+## Quick Start
 
-## Install from npm
+Requirements: Node.js 22+, ffmpeg in PATH, and a Replicate API token.
 
 ```bash
 npm install -g @telepat/rilo
-rilo --help
-```
-
-Or without global install:
-
-```bash
-npx @telepat/rilo --help
-```
-
-## CLI Quick Reference
-
-### Generate a video from a story
-
-```bash
-rilo --project <name> --story-file <path>
-```
-
-Examples:
-```bash
-# First run: create project and start generation
-rilo --project wedding-case --story-file ./story.txt
-
-# On subsequent runs: reuse story
-rilo --project wedding-case
-
-# Force restart from earlier stages (after config change)
-rilo --project wedding-case --force
-```
-
-### Configure settings
-
-```bash
 rilo settings
+rilo --project demo --story-file ./story.txt
 ```
 
-Opens an interactive menu to set API tokens, timeouts, and binary paths.
-
-### Open the Rilo home folder
-
-```bash
-rilo home
-```
-
-Opens `~/.rilo`, the default location for saved settings, projects, and generated output.
+Expected outcome:
 
-### Help and version
+- A project folder is created under `projects/demo/`.
+- The full pipeline runs through script, voiceover, keyframes, segments, and composition.
+- Final video is written to `projects/demo/final.mp4`.
+- Dashboard preview available via `rilo preview`.
 
-```bash
-rilo --help                    # Show usage
-rilo --version                 # Show version
-```
+## Requirements
 
-### Invocation methods
+- Node.js 22+
+- ffmpeg in PATH
+- Replicate API token
+- macOS, Linux, or Windows
 
-| Method | Command |
-|--------|---------|
-| **Global install** | `rilo --project <name> --story-file <path>` |
-| **No install (npx)** | `npx @telepat/rilo --project <name> --story-file <path>` |
-| **Local dev** | `npm run dev -- --project <name> --story-file <path>` |
+## How It Works
 
-### Key flags
+Rilo runs a staged pipeline: script generation, voiceover synthesis, shot prompt generation, keyframe rendering, segment generation, and final video composition. Each stage writes checkpointed artifacts so you can resume or regenerate selectively.
 
-| Flag | Type | Notes |
-|------|------|-------|
-| `--project` | `<name>` | **Required.** Project identifier; creates `projects/<name>/` |
-| `--story-file` | `<path>` | Path to story text file (required on first run) |
-| `--force` | flag | Restart from earlier stages; used after config changes |
+Configuration merges CLI flags, environment variables, and `~/.rilo/config.json` with schema defaults. The preview dashboard (`rilo preview`) starts a local API, worker, and Vite React frontend for monitoring and editing.
 
-### Common tasks
+## Using With AI Agents
 
-**Update project config and regenerate:**
-```bash
-# Edit projects/wedding-case/config.json (aspect ratio, models, etc.)
-rilo --project wedding-case --force
-```
+Rilo provides multiple surfaces for agentic and automated workflows:
 
-**Change app settings (tokens, timeouts, binary paths):**
-```bash
-rilo settings
-# Arrow keys to navigate, Enter to edit, "Done" to save
-```
-
-**Open the default app folder for projects/output:**
-```bash
-rilo home
-# Opens ~/.rilo in your system file manager
-```
-
-**Check where generated files are stored:**
-```bash
-ls projects/wedding-case/
-# Outputs: config.json, story.md, final.mp4, artifacts.json, run-state.json, assets/, logs/
-```
+- **CLI automation** — All generation is driven by CLI flags and environment variables. No interactive prompts are required after initial setup.
+- **HTTP API** — `rilo preview` starts an Express API with full job and project CRUD, asset serving, and webhook endpoints. Bearer-token auth via `Authorization: Bearer <API_BEARER_TOKEN>`.
+- **OpenAPI spec** — Auto-generated OpenAPI 3.1 spec for schema-driven agent integration.
+- **Webhooks** — Subscribe to job lifecycle events for external orchestration.
+- **Firebase Functions** — Deploy `src/api/firebaseFunction.js` for serverless API hosting.
+- **Agent docs** — [API Reference](https://docs.telepat.io/rilo/reference/api-reference) covers endpoints, auth, and webhooks.
 
----
+## Security And Trust
 
-## CLI Documentation
+- API tokens and Replicate credentials are stored in the OS keystore (macOS Keychain, Windows Credential Manager, Linux Secret Service) when available.
+- Falls back to an AES-256 encrypted file at `~/.rilo/.secrets` if no native keystore is available.
+- Environment variables (`RILO_REPLICATE_API_TOKEN`, `RILO_API_BEARER_TOKEN`) take highest precedence and override stored values.
+- Preview `--expose` mode should only be used on trusted networks or isolated environments.
 
-For comprehensive CLI documentation, see:
-- **[Quickstart](/docs.telepat.io/rilo/getting-started/quickstart)** — Step-by-step guide to your first generation
-- **[CLI Reference](/docs.telepat.io/rilo/reference/cli-reference)** — All commands, flags, and invocation methods
-- **[Complete Config Schema](/docs.telepat.io/rilo/reference/config-schema)** — Every config key with types and defaults
-- **[Configuration Guide](/docs.telepat.io/rilo/guides/configuration)** — Project and app settings with examples
-- **[Troubleshooting](/docs.telepat.io/rilo/guides/troubleshooting)** — Common errors and solutions
-- **[Environment Variables](/docs.telepat.io/rilo/reference/environment-variables)** — Setting precedence and env var reference
+## Documentation And Support
 
-## Full Documentation
+- [Documentation site](https://docs.telepat.io/rilo)
+- [Quickstart](https://docs.telepat.io/rilo/getting-started/quickstart)
+- [CLI Reference](https://docs.telepat.io/rilo/reference/cli-reference)
+- [Configuration Guide](https://docs.telepat.io/rilo/guides/configuration)
+- [API Reference](https://docs.telepat.io/rilo/reference/api-reference)
+- [Troubleshooting](https://docs.telepat.io/rilo/guides/troubleshooting)
+- [Repository](https://github.com/telepat-io/rilo)
+- [npm package](https://www.npmjs.com/package/@telepat/rilo)
 
-Guides, API reference, architecture notes, and advanced configuration:
+## Contributing
 
-https://docs.telepat.io/rilo/
+Contributions are welcome. See [Development](https://docs.telepat.io/rilo/contributing/development) for local setup, build commands, and test workflows.
 
 ## License
 
-MIT
+MIT. See [LICENSE](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,100 @@
+<p align="center"><img src="./assets/avatar/rilo-logo.webp" width="128" alt="Rilo"></p>
+<h1 align="center">Rilo</h1>
+<p align="center"><em>将故事转化为成品视频——AI 生成脚本、配音、关键帧和合成，一条命令完成。</em></p>
+
+<p align="center">
+  <a href="https://docs.telepat.io/rilo">📖 文档</a>
+  · <a href="./README.md">🇺🇸 English</a>
+  · <a href="./README.zh-CN.md">🇨🇳 简体中文</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/telepat-io/rilo/actions/workflows/ci.yml"><img src="https://github.com/telepat-io/rilo/actions/workflows/ci.yml/badge.svg?branch=main" alt="Build"></a>
+  <a href="https://codecov.io/gh/telepat-io/rilo"><img src="https://codecov.io/gh/telepat-io/rilo/graph/badge.svg" alt="Codecov"></a>
+  <a href="https://www.npmjs.com/package/@telepat/rilo"><img src="https://img.shields.io/npm/v/@telepat/rilo" alt="npm"></a>
+  <a href="https://github.com/telepat-io/rilo/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="License"></a>
+</p>
+
+Rilo 将故事转化为成品视频——AI 生成脚本、配音、关键帧和合成，一条命令完成。
+
+用纯文本写下您的故事。Rilo 处理剩下的部分：脚本生成、旁白配音、视觉关键帧、视频片段和最终合成——以及可选的字幕对齐与烧录。
+
+专为需要大规模、可复现、高质量视频生产而无需手动编辑的创作者和团队打造。
+
+## 功能特性
+
+- **完整流水线，一条命令** — 故事 → 脚本 → 配音 → 关键帧 → 片段 → 最终视频。`rilo --project demo --story-file ./story.txt`
+- **检查点运行** — 每个阶段保存产物。可恢复或选择性重新生成任何阶段。`rilo --project demo --force`
+- **您的模型，您做主** — 选择 T2I 和 I2V 模型。覆盖每个模型的选项。随时切换。
+- **代码驱动的工作流** — 确定性编排、检查点和产物管理。Token 用于生成，而非基础设施。
+- **字幕对齐与烧录** — 自动将字幕对齐到配音时间轴。烧录到最终视频中。
+- **预览控制台** — Web 界面用于项目管理、重新生成和资产预览。`rilo preview`
+- **HTTP API 与 Webhook** — Bearer 令牌认证、OpenAPI 3.1 规范、Webhook 订阅。支持 Firebase 或本地。
+- **跨平台** — macOS、Linux、Windows。需要 Node.js 22+ 和 ffmpeg。
+
+## 快速开始
+
+环境要求：Node.js 22+、PATH 中有 ffmpeg、Replicate API token。
+
+```bash
+npm install -g @telepat/rilo
+rilo settings
+rilo --project demo --story-file ./story.txt
+```
+
+预期结果：
+
+- 在 `projects/demo/` 下创建项目文件夹。
+- 完整流水线依次运行脚本、配音、关键帧、片段和合成。
+- 最终视频写入 `projects/demo/final.mp4`。
+- 可通过 `rilo preview` 打开仪表板预览。
+
+## 环境要求
+
+- Node.js 22+
+- PATH 中有 ffmpeg
+- Replicate API token
+- macOS、Linux 或 Windows
+
+## 工作原理
+
+Rilo 运行分阶段流水线：脚本生成、语音合成、镜头提示生成、关键帧渲染、片段生成和最终视频合成。每个阶段都会写入检查点产物，因此你可以恢复或有选择地重新生成。
+
+配置会合并 CLI 标志、环境变量和 `~/.rilo/config.json`，并以模式默认值兜底。预览仪表板（`rilo preview`）启动本地 API、worker 和 Vite React 前端，用于监控和编辑。
+
+## 与 AI Agent 一起使用
+
+Rilo 为智能体和自动化工作流提供多种接口：
+
+- **CLI 自动化** — 所有生成均由 CLI 标志和环境变量驱动。初始设置后无需交互式提示。
+- **HTTP API** — `rilo preview` 启动 Express API，提供完整的 job 和 project CRUD、资源服务和 webhook 端点。通过 `Authorization: Bearer <API_BEARER_TOKEN>` 进行 Bearer token 认证。
+- **OpenAPI 规范** — 自动生成 OpenAPI 3.1 规范，支持基于模式的智能体集成。
+- **Webhook** — 订阅 job 生命周期事件，用于外部编排。
+- **Firebase Functions** — 部署 `src/api/firebaseFunction.js` 实现无服务器 API 托管。
+- **Agent 文档** — [API 参考](https://docs.telepat.io/rilo/reference/api-reference) 涵盖端点、认证和 webhook。
+
+## 安全与信任
+
+- API token 和 Replicate 凭证在 OS 密钥库可用时保存（macOS Keychain、Windows Credential Manager、Linux Secret Service）。
+- 如果无原生密钥库可用，则回退到 `~/.rilo/.secrets` 的 AES-256 加密文件。
+- 环境变量（`RILO_REPLICATE_API_TOKEN`、`RILO_API_BEARER_TOKEN`）优先级最高，会覆盖已存储的值。
+- Preview `--expose` 模式应仅在可信网络或隔离环境中使用。
+
+## 文档与支持
+
+- [文档站点](https://docs.telepat.io/rilo)
+- [快速上手](https://docs.telepat.io/rilo/getting-started/quickstart)
+- [CLI 参考](https://docs.telepat.io/rilo/reference/cli-reference)
+- [配置指南](https://docs.telepat.io/rilo/guides/configuration)
+- [API 参考](https://docs.telepat.io/rilo/reference/api-reference)
+- [故障排查](https://docs.telepat.io/rilo/guides/troubleshooting)
+- [仓库](https://github.com/telepat-io/rilo)
+- [npm 包](https://www.npmjs.com/package/@telepat/rilo)
+
+## 贡献
+
+欢迎贡献。请参阅[开发指南](https://docs.telepat.io/rilo/contributing/development)了解本地环境搭建、构建命令和测试工作流。
+
+## 许可证
+
+MIT。详见 [LICENSE](./LICENSE)。