red-future/media

Fork 0

Files

张斌 9bc48060dc ci/cd调整

2026-06-10 16:10:10 +08:00

7.7 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# 下载依赖
go mod download

# 编译
go build -o media main.go

# 运行（开发）
go run main.go

# 格式化代码
go fmt ./...

# 代码检查
go vet ./...

# Docker 构建（多阶段构建，包含 FFmpeg 和 whisper 运行时）
docker build -t media .

# Docker 运行
docker run -p 3010:3010 media

Architecture

这是一个多媒体处理微服务项目，基于 GoFrame 框架开发，提供视频处理、音频提取、语音识别等功能。

目录结构

main.go                 # 应用入口
config.yml              # 配置文件
consts/                 # 常量定义
  - video/              # 视频相关常量（包括视频分析任务状态）
controller/             # HTTP 控制器层（路由入口）
  - audio/              # 音频相关接口
  - video/              # 视频相关接口（拼接、剪切、分析）
  - common/             # 公共工具
  - scene/              # 场景检测接口
  - image/              # 图片处理接口
service/               # 业务逻辑层
  - video/             # 视频服务（拼接、剪切、分析、分析队列）
  - audio/             # 音频提取服务
  - asr/               # 语音识别（Whisper）
  - scene/             # 场景检测
  - image/             # 图片处理
  - setup/             # 初始化服务
dao/                   # 数据访问层
  - audio/             # ASR 任务数据访问
  - video/             # 视频分析任务数据访问
  - image/
model/                 # 数据模型
  - dto/               # 传输对象（请求/响应）
    - video/           # 视频相关 DTO（包括视频分析）
  - entity/            # 数据库实体
    - video/           # 视频相关实体（包括分析任务）
resource/              # 静态资源（日志、临时文件）
sql/                   # 数据库 SQL
  - video_analysis_task.sql - 视频分析任务表建表SQL

核心功能

功能	说明	依赖
视频拼接	支持多个视频拼接，提供 fast（无损 concat demuxer）和 reencode（重编码归一化）两种模式，可上传结果到 MinIO，支持同步和异步任务	FFmpeg
视频分镜剪切	根据分镜时间片段列表剪切视频并重新拼接输出，支持同步和异步任务	FFmpeg
音频提取	从视频文件中提取音频，支持 mp3/aac/wav/ogg/flac 多种格式	FFmpeg
语音识别	异步语音转文字任务，基于 OpenAI Whisper，支持 whisper.cpp 加速	FFmpeg + Whisper/whisper.cpp
场景检测	视频场景切分检测，提取关键帧，输出场景信息	FFmpeg + ffprobe
视频分析	基于 Marlin-2B Video VLM 大模型进行视频理解，自动生成场景描述、事件切分和向量化，存入 RAG 系统	FFmpeg + 外部 Marlin-2B VLM 服务

启动初始化

setup 包在 init() 阶段自动执行，启动时会检查 FFmpeg 和 Whisper 依赖是否可用
自动检测 whisper-cpp > whisper > python -m whisper 三个优先级
如果依赖缺失会输出警告提示安装

API 端点

视频拼接：

POST /video/concat - 视频拼接（URL 输入，同步）
POST /video/concat/async - 视频拼接（URL 输入，异步）
POST /video/concat/upload - 视频拼接（文件上传，同步）
POST /video/concat/upload/async - 视频拼接（文件上传，异步）
GET /video/concat/task/{taskId} - 查询异步拼接任务结果

视频分镜剪切：

POST /video/cut - 视频分镜剪切（URL 输入，同步）
POST /video/cut/async - 视频分镜剪切（URL 输入，异步）
GET /video/cut/task/{taskId} - 查询异步剪切任务结果

语音识别：

POST /audio/transcribe - 创建语音转文字异步任务
GET /audio/task/{taskId} - 获取转写任务详情
GET /audio/task/{taskId}/progress - 获取任务进度
GET /audio/tasks - 获取任务列表

视频分析（规划中）：

POST /video/analysis - 创建视频分析异步任务（基于 Marlin-2B VLM）
GET /video/analysis/task/{taskId} - 查询分析任务结果
GET /video/analysis/task/{taskId}/progress - 查询分析任务进度
POST /video/analysis/retry/{taskId} - 重试失败的分析事件

Note

: scene 场景检测和 image 图片处理服务目录已创建，但 HTTP 端点尚未实现暴露。音频提取服务已实现但尚未暴露。

依赖外部服务

PostgreSQL - 数据存储
Redis - 缓存
Consul - 服务发现
Jaeger - 链路追踪
OSS/MinIO - 文件存储（通过内部 oss 微服务上传）
FFmpeg - 多媒体处理
Whisper - 语音识别
Marlin-2B VLM 服务 - 视频理解大模型（提供字幕生成、事件定位功能）

内部依赖

项目依赖内部私有公共包 gitea.redpowerfuture.com/red-future/common，包含 HTTP 路由注册、用户信息解析、Consul、Jaeger 等基础设施封装。Docker 构建过程中已配置访问凭证。

Docker 镜像

多阶段构建镜像包含：

编译后的二进制
FFmpeg 运行时
Python 3 + openai-whisper（Python 版本，用于语音识别）
非 root 用户 appuser 运行
暴露端口 3010

架构设计

分层架构：

controller - HTTP 入口，参数解析，调用 Service，返回响应
service - 业务逻辑实现，每个功能领域一个子包
dao - 数据访问层，数据库操作
model - 数据模型，dto 存放请求/响应传输对象，entity 存放数据库实体

设计模式：

使用 GoFrame 框架的依赖注入模式
所有 Service 和 Controller 都使用单例模式（var Xxx = new(XxxStruct)）
遵循标准的 Go 命名约定
临时文件处理完需要及时清理（使用 defer os.Remove()）

异步任务处理：

长时任务（视频拼接、视频剪切、语音识别）都支持异步执行
同步模式直接等待结果返回，异步模式创建任务后立即返回任务 ID
异步任务状态持久化到数据库，可通过任务 ID 查询进度和结果
支持回调 URL，任务完成后会回调通知调用方
任务执行使用 goroutine 异步处理

用户身份：

所有接口优先从请求头 Authorization / X-User-Info 解析用户信息
解析失败使用默认 admin / tenantId=1 用于开发和调试

配置

主要配置在 config.yml:

Server:

server.address - 监听地址（默认 :3010）
server.clientMaxBodySize - 上传文件大小限制（默认 200MB）

限流：

rate.limit - 每秒请求限制（默认 200）
rate.burst - 突发请求允许量（默认 300）

FFmpeg:

ffmpeg.path - FFmpeg 可执行文件路径，留空则从 PATH 自动查找
ffmpeg.temp_dir - 临时文件目录（存放上传的视频和处理输出）

Whisper 语音识别:

whisper.path - Whisper 可执行文件路径，留空自动查找
whisper.model - 默认模型（tiny(最快)/base/small/medium）
whisper.language - 默认语言（zh=中文, en=英文）
whisper.model_dir - 模型缓存目录，留空使用默认 (~/.cache/whisper/)
whisper.threads - CPU 线程数（限制资源占用，建议 2-4）

视频分析:

analysis.concurrency - 并发处理数，控制同时处理的分析任务数量（默认 1，串行处理，建议不超过 CPU 核心数）
analysis.maxRetries - 单事件最大重试次数，失败时自动重试（默认 3）

外部服务:

database - PostgreSQL 数据库配置
redis - Redis 配置
consul - Consul 服务发现配置
jaeger - Jaeger 链路追踪配置
filePrefix - OSS/MinIO 文件访问地址前缀

7.7 KiB Raw Permalink Blame History Unescape Escape