# CastCaster

[![CI](https://github.com/Lax/castcaster/actions/workflows/ci.yml/badge.svg)](https://github.com/Lax/castcaster/actions/workflows/ci.yml)
[![Gem](https://img.shields.io/gem/v/castcaster)](https://rubygems.org/gems/castcaster)
[![License](https://img.shields.io/github/license/Lax/castcaster)](LICENSE)
[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.0-red)](https://ruby-lang.org)

统一直播流管理平台。

基于 Nginx 管理 RTMP/HLS 直播流，支持每个频道的独立 FFmpeg 任务容器（中继、自适应转码、截图、测试流），隔离性好，易于扩展。

## 快速开始

```bash
# 安装并初始化
gem install castcaster
castcaster init

# 添加测试频道
castcaster channel add --name demo

# 生成 compose.yml 并启动
castcaster deploy
docker compose up -d
```

打开 `http://localhost:8080/channel/demo`，点击播放按钮即可看到带时间戳的测试画面。

### 源类型

```bash
# 测试流 — 内部生成（默认）
castcaster channel add --name demo

# 拉流 — 从外部 RTMP 源中继
castcaster channel add --name relay \
  --source-type rtmp_pull \
  --source rtmp://example.com/live/stream

# 拉流 + 自适应转码
castcaster channel add --name news \
  --source-type http_pull \
  --source http://example.com/stream \
  --transcode 720p,480p

# 拉流 + 截图
castcaster channel add --name camera \
  --source-type http_pull \
  --source http://example.com/stream \
  --snapshot 5

# 推流 — OBS/FFmpeg 推流到 CastCaster
castcaster channel add --name mychannel --source-type rtmp_push
# OBS: rtmp://host:1935/live/mychannel
```

## 架构

```
Browser───:80 ──→ Traefik (可选) ──→ nginx :8080
                   │                       ├── /hls/live/* → HLS 切片
                   │                       ├── /api/*      → proxy → webui:8081
                   │                       ├── /           → proxy → webui:8081
                   │                       └── RTMP :1935  → RTMP 接入
                   │
                   └── :443 (HTTPS, Let's Encrypt)

FFmpeg 容器（每个频道）：
  test-<name>    → teststream.sh（内部测试流）
  relay-<name>   → relay.sh（RTMP/HTTP 拉流中继）
  adaptive-<name>→ adaptive.sh（多码率转码）
  snapshot-<name>→ snapshot.sh（定时截图）
```

## 环境要求

- **Ruby** >= 3.0
- **Docker** + **Docker Compose**（v2）

### Docker 镜像

| 镜像 | 来源 | 用途 |
|------|------|------|
| `ghcr.io/lax/castcaster-nginx` | 本地构建 | Nginx（RTMP + HLS + 反向代理） |
| `ghcr.io/lax/castcaster-webui` | 本地构建 | Web 管理界面 |
| `ghcr.io/lax/castcaster-ffmpeg` | 本地构建 | FFmpeg 中继/转码/截图 |
| `traefik:v3.0` | Docker Hub | 反向代理 + SSL（可选） |

## 命令行

### `init`

```bash
castcaster init
```

生成：`castcaster.yml`、`castcaster.token`、`channels/`、`hls/`、`logs/`、`data/`。

### `channel add`

```bash
# 测试流（默认）
castcaster channel add --name demo

# 拉流
castcaster channel add --name relay --source-type rtmp_pull --source rtmp://example.com/live/stream

# 拉流 + 自适应转码
castcaster channel add --name news \
  --source-type http_pull \
  --source http://example.com/stream \
  --transcode 720p,480p

# 截图
castcaster channel add --name camera \
  --source-type http_pull \
  --source http://example.com/stream \
  --snapshot 5

# 推流
castcaster channel add --name mychannel --source-type rtmp_push
```

### `channel list / start / stop / rm / update`

```bash
castcaster channel list
castcaster channel start news
castcaster channel stop news
castcaster channel rm radio
castcaster channel update news --source-type rtmp_pull
```

### `config`

预览生成的 nginx 配置。

```bash
castcaster config
```

### `deploy`

生成 compose.yml（可选 Traefik 配置）。

```bash
castcaster deploy                       # Docker Compose（默认）
castcaster deploy --with-traefik        # + Traefik SSL
castcaster deploy --mode swarm          # Docker Swarm

```

### `doctor`

检查系统环境。

```
Ruby           ruby 3.4.1
Docker         Docker version 28.4.0
Compose        Docker Compose version v2.39.3
nginx          available
ffmpeg         available
webui          available
config.yml     ok
```

## Web 管理面板

`http://localhost:8080`

- 仪表盘 — 频道列表与状态
- 频道页面 — hls.js 播放器、RTMP/HLS 连接信息
- REST API — `GET /api/channels`, `GET /api/status`

> 注意：启动/停止操作通过 CLI 管理（`castcaster channel start/stop`）

## 部署模式

### Docker Compose（默认）

```bash
castcaster deploy
docker compose up -d
```

### Docker Compose + Traefik

```bash
castcaster deploy --with-traefik
docker compose up -d
```

### Docker Swarm

```bash
castcaster deploy --mode swarm
docker stack deploy -c docker-stack.yml castcaster
```

## 开发

```bash
# 从源码构建
git clone https://github.com/Lax/castcaster.git
cd castcaster
gem build castcaster.gemspec
gem install castcaster-*.gem

# 运行测试
rake test
rake syntax
```

| 分支 | 说明 |
|------|------|
| `dev` | 活跃开发 |
| `main` | 产品发布分支 |

## License

MIT

**项目主页:** [https://liulantao.com/castcaster](https://liulantao.com/castcaster)