映流 · DSH 视频工作台

在对话中构思影片，在工作台里调整镜头，最后导出本地 MP4。

映流（yingliu-video-studio）是 DSH Desktop 的视频制作插件。你可以把图片、文字、音频和视频交给工作台，使用 DSH 模型编排分镜、编写动画；也可以单独接入生图、生视频和配音服务，把生成的素材加入影片，再自己修改文案、安排声音、逐帧检查画面。分镜、素材、前端源码和修改历史都保存在本地工程中，方便继续编辑。

当前代码版本：0.6.0，新增模型与素材生成、视频片段和协作制作。插件按所需的宿主接口检查兼容性，不再绑定 DSH 发布版本号，详见宿主兼容机制。本轮多模态测试和历史 Desktop 验收的范围见 0.6.0 验收说明。

工作台中的示例影片。本文七张界面截图保留自 0.4.0 的独立测试环境，使用专门制作的演示数据；0.6.0 新增的模型与素材生成、视频片段和协作制作面板以本文操作说明为准。截图不代表云端模型的生成效果，点击可查看大图。

目录

• 可以用它做什么
• 安装与首次配置
• 制作第一部影片
• 自定义与导入视频风格
• 在工作台里调整影片
• 生成图片和视频素材
• 把视频片段加入镜头
• 使用协作制作
• 添加配音、音乐和音效
• 检查画面并导出
• 管理影片和会话
• 保存、备份与恢复
• 常见问题
• 开发与扩展

可以用它做什么

你想做的事	在映流中的做法
用图文制作介绍片、知识讲解或展示视频	提供主题和素材，让模型生成分镜与前端动画
修改某个镜头的文案、色彩或节奏	编辑镜头属性，或用一句话说明修改要求
精细调整动画和布局	编辑每个镜头的 HTML、CSS 和 JavaScript
用模型生成图片或短视频	配置对应媒体服务，生成候选素材，检查后采用
把已有视频与代码动画组合	导入视频，设置裁剪、速度和原声，再叠加文字与图形
连续完成规划、画面和配音	在「协作制作」选择制作范围与方式，按步骤查看结果
加入旁白、背景音乐和音效	导入音频并安排片段，或使用已配置的配音服务
检查某个瞬间的实际画面	播放预览、逐帧定位、查看关键帧，或导出当前帧 PNG
继续制作已有影片	从影片首页打开工程，查看历史、恢复修改、再次导出

映流把前端代码画面与视频片段组合，使用本机浏览器和 FFmpeg 输出整片。插件已包含节点编辑器与浏览器驱动，无需安装 ComfyUI，也不需要运行独立版映流或公共网关。只有使用生图、生视频等功能时，才需要配置兼容的媒体服务。

目前支持图片、文字、音频和视频输入，每个镜头可安排一段主视频。暂不提供多视频轨道剪辑、完整的图层关键帧编辑器、云端整片渲染或多人实时协作。协作制作是固定制作流程；子代理协作则使用 DSH 自身的代理与任务能力，详见管理影片和会话。

安装与首次配置

1. 准备运行环境

需要准备	用途	什么时候需要
DSH Desktop，提供插件所需的服务接口	运行插件，提供会话、模型和任务服务	始终需要
本机 Chrome 或 Chromium	捕获实际画面帧并参与视频渲染	实际帧检查和导出时
FFmpeg	视频导入与规范化、编码、音频处理与混音	导入视频、导出或处理声音时
ffprobe	读取音频、视频和成片信息	导入媒体、检查产物时
DSH 中已配置的模型	理解需求、生成分镜和画面、按要求改片	使用模型创作时
生图或生视频服务	生成图片、视频候选素材	需要模型生成媒体时，可选
本机语音或自有语音服务	把旁白文字合成为音频	需要自动配音时，可选

手动编辑已有工程、导入素材、预览和本地导出不需要调用聊天模型。分镜和代码创作使用 DSH 模型；生图、生视频及 Speech 配音在插件内分别配置，没有媒体服务也可以用自己的素材完成影片。

尚未安装浏览器时，可以从 Chrome 官网下载。FFmpeg 可从其下载页面查找对应系统的构建；macOS 用户如果已安装 Homebrew，也可以按 FFmpeg 软件包说明运行 brew install ffmpeg。完成安装后，按下文检查 FFmpeg 和 ffprobe 的路径。

2. 安装并启用插件

1. 在 DSH 插件管理中使用 npm 包名 yingliu-video-studio@0.6.0 安装；也可准备与当前版本对应的安装包，例如 yingliu-video-studio-0.6.0.tgz。可使用维护者提供的包，或按开发与扩展中的步骤自行构建。
2. 打开 DSH 的 插件管理 → 添加插件，填写 yingliu-video-studio@0.6.0；使用本地包时填写 .tgz 文件的绝对路径。
3. 安装完成后启用插件。安装与启用是两个步骤，请确认插件已处于运行状态。
4. 点击 DSH 侧栏带胶片图标的 映流 · 视频工作台，进入影片首页；侧栏收起时可点击相同图标。

普通使用不需要克隆源码，也不需要执行后面的开发命令。

3. 检查本地渲染工具

在影片首页点击 环境设置；进入工作台后，也可以点击右上角的 环境。

三个工具分别显示「已就绪」或「待配置」。修改路径后，点击「保存并检查环境」。

插件会尝试自动查找工具。如果显示「待配置」，填写对应可执行文件的绝对路径，而不是安装目录。macOS 上常见的路径如下，具体以你的安装位置为准：

工具	路径示例
Google Chrome	/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
FFmpeg（Apple Silicon 上的 Homebrew）	/opt/homebrew/bin/ffmpeg
ffprobe（Apple Silicon 上的 Homebrew）	/opt/homebrew/bin/ffprobe

已经安装 FFmpeg 的用户可以在终端运行以下命令查找位置；没有输出通常表示工具未安装，或不在当前终端的搜索路径中。

command -v ffmpeg
command -v ffprobe

点击 保存并检查环境，确认三个工具均为「已就绪」。如果修改了本机工具的安装位置，再来这里更新路径即可。

制作第一部影片

可以从 DSH 会话开始，也可以直接在工作台中操作。两种方式编辑的是同一份影片工程，制作过程中可以随时切换。

方式一：在 DSH 会话中制作

适合已经在对话中整理好主题、文案或素材的情况。

1. 打开一个可以使用视频工具的 DSH 会话，提供主题和需要的图片、文字或音频；已有本地视频也可以在工作台导入。

2. 说明影片主题、目标片长、画幅和希望呈现的内容。必须准确出现的人名、产品名与数据，请一并提供。

3. 让模型创建影片工程，先整理分镜，再生成画面。例如：

   用我上传的三张街景照片，制作一部约 30 秒的中文城市漫步短片。横屏 16:9，1920 × 1080，30 FPS。分为开场、街巷细节和收尾三个部分，文字简洁，图片缓慢移动。先创建工程并整理分镜，再生成画面。保留可编辑的文字、颜色和图片参数，导出前检查实际帧。这次先做无声版。

4. 从视频工具的结果卡片打开工作台，查看对应影片、镜头或指定帧。

5. 需要修改时，可以继续在原会话中描述范围：

   只修改第二个镜头：把屏幕主文字改为“慢一点，看见街角的日常”，图片改为缓慢放大。保留其他镜头和声音，修改后检查这个镜头的首帧、中间帧和末帧。

6. 确认内容后，让模型导出，或在工作台点击 导出视频。

会话中的分镜和代码制作使用当前会话模型。配置媒体模型后，也可以让模型用 video_media 生成素材、查询任务和采用结果。渲染、配音与媒体等待会显示为后台任务；媒体任务的「停止等待」和「请求远端取消」含义不同，详见生成任务的状态与恢复。普通使用无需手写工具参数，开发者可查阅 API 文档及多模态制作说明。

方式二：从工作台开始

首页集中管理影片。可以先建立工程、导入素材，再选择模型生成分镜。

1. 点击 新建影片，填写「影片名称」「主题与制作想法」「初始目标片长（秒）」和「初始输出比例」。会话关联可以先留空。
2. 点击 创建影片 进入工作台。初始输出默认为所选比例、短边 1080 像素、30 FPS，之后可以修改。
3. 在左侧 资产库 点击 导入素材 或 添加文字。支持的格式见下表。
4. 在顶部 创作模型 中选择 DSH 已配置的提供方和具体模型。如果没有可选模型，先到 DSH 中完成模型配置。
5. 点击 生成分镜，检查每个镜头的内容、素材和时长，再点击 生成画面，让模型编写镜头动画。
6. 需要模型生成图片或视频时，打开 模型与素材生成；已有视频可按视频片段说明安排。也可以使用 协作制作 连续完成规划和制作。
7. 点击 预览，根据画面继续调整。需要声音时，按配音说明添加；完成后检查并导出。

素材类型	支持格式	添加方式
图片	PNG、JPEG、WebP	导入素材，或把图片拖入资产库
文字	TXT、Markdown，也可直接粘贴	导入素材，或点击「添加文字」
音频	WAV、MP3、M4A、AAC、FLAC、OGG	导入素材，然后在「声音与配音」中安排片段
视频	MP4、MOV、WebM、MKV 等可通过媒体检查的格式	导入素材，或在「模型与素材生成」中从本地路径导入

「生成分镜」和「生成画面」是两个步骤。 新建时的「创建并生成分镜」可以合并创建与分镜步骤，之后仍需要生成画面。这里的「生成画面」指编写前端动画；生图、生视频使用另一个 模型与素材生成 面板。

再次点击「生成分镜」会重新编排整套镜头，并为新镜头建立默认源码。 已有影片只需局部改动时，请使用镜头属性或「修改这个镜头」，也可以在协作制作中选择「当前选中镜头」。

自定义与导入视频风格

影片首页的 视频制作风格 是本地风格库入口。可以新建自己的风格说明，也可以导入已有的视频制作风格；在新建影片时选中一种风格后，它会随影片保存，并作为分镜和镜头生成的视觉、声音与节奏参考。

支持单个 Markdown（.md、.markdown）、TXT 或 JSON 文件，也支持 ZIP 风格包和包含上述文件的文件夹。Markdown/TXT 内容会作为风格描述；JSON 可提供 name、description、prompt（或 stylePrompt、style_prompt、instructions）等字段。文件夹或 ZIP 中可用 STYLE.md 配合 style.json 元数据，单个风格目录会作为一项导入。示例：

{
  "name": "城市水彩",
  "description": "轻盈的城市漫步短片",
  "prompt": "用透明水彩色块、松动的线稿和缓慢的镜头移动表现街巷。"
}

导入只读取文本风格说明，不运行包内代码。风格库保存在本机 DSH 视频工程目录的 styles.json 中；删除库项目不会移除已复制到影片中的风格。

在工作台里调整影片

认识几个主要区域

区域	用来做什么
顶部工具栏	选择创作模型，设置输出规格，生成、预览和导出
左侧「资产库」	导入、搜索和查看图片、文字、音频、视频
中间「分镜画布」	查看素材与镜头的关系，连接播放顺序
右侧「镜头属性」	修改选中镜头的文字、时长、颜色、运动、图片位置和视频片段
画布下方「镜头顺序」	选择镜头、拖动排序，快速查看整片结构
下方工作面板	切换影片预览、模型与素材生成、协作制作、声音、源码、历史、任务和成片

调整内容和顺序

• 修改画面文字：选中镜头，在右侧修改「屏幕主文字」和「补充文字」。镜头标题用于标识镜头，与画面中显示的文字分别编辑。
• 调整时长：修改「时长（秒）」。实际片长等于所有镜头时长之和；「目标片长」用于初始规划，之后增删镜头不会强行缩放其他镜头。
• 更换素材：在「素材关联」中选择「使用」或「参考」。「使用」让素材参与画面；「参考」帮助模型理解风格与构图，不会自动显示在成片里。仅把素材导入资产库，还没有把它安排进镜头。
• 改变图片构图：展开「图片位置与缩放」，调整横向位置、纵向位置、缩放和适应方式。
• 调整顺序：拖动镜头条，或连接画布上的镜头顺序端口。若提示「主链待连接」，检查是否有断链、分叉或循环，也可以点击「按镜头条连接」。
• 整理画布：拖动空白处平移，滚轮缩放；用「全图概览」「聚焦选中」和「整理画布」找回节点。

画布上的节点位置只影响工作区布局。视频中的图片位置要在镜头属性中调整。参数修改后，如果预览提示内容已更新，点击 刷新预览 查看效果。

用自然语言改片

在 影片预览 右侧选择「当前镜头」或「整部影片」，输入要求，然后点击 修改这个镜头 或 修改整部影片。

可以写：“标题从左侧滑入，图片缓慢放大，背景改成奶油色，保持当前时长。”描述中同时说明希望保留的内容，通常更容易得到所需结果。

直接编辑源码

选中镜头，打开 前端源码，切换 HTML、CSS、JS 进行编辑。点击 保存源码，或使用 Ctrl / ⌘ S，再刷新预览检查结果；出现问题时可以 恢复上次可用。

每个镜头有独立源码。先保存，再刷新预览，就能检查这次修改。

源码草稿会按工程和镜头保留。草稿尚未提交时，不会进入预览或成片，还会阻止预览、导出等操作。 可以从顶部「查看源码草稿」进入，保存或丢弃后继续；也可下载草稿备份。如果模型已更新工程，请先对照最新源码，再决定是否将草稿保存到当前版本。

自定义源码需要读取 ctx.params 中的共享参数，右侧属性才能控制对应内容。写死在源码里的文字或颜色，需要修改源码或让模型修改。源码不会自动还原成可视图层。场景接口和示例见 API 文档。

生成图片和视频素材

1. 配置媒体连接和模型

打开工作台下方的 模型与素材生成 → 配置模型连接。模型中心把「连接」和「模型」分开：连接保存服务地址与认证方式，一个连接可以添加多个模型；「创作角色」指定协作制作默认使用哪个模型。

需要的能力	在哪里配置	接口要求
分镜规划、场景代码、关键帧理解	DSH 模型配置与工作台顶部「创作模型」	使用 DSH 已有的模型和代理能力；视觉检查需模型支持图片输入
生成图片	插件模型中心，选择「生图（Images Generations）」	兼容 /images/generations，返回图片 URL 或 Base64
生成视频	插件模型中心，选择「生视频（映流网关 v1）」	实现映流媒体网关 v1 的提交、查单和按请求 ID 查询接口
协作制作中的配音	插件模型中心，选择「配音（Speech）」	兼容 /audio/speech；也可沿用原有配音设置

1. 在「已保存的连接」中选择 新连接，填写连接名称、接口协议、API Base URL、认证方式和 API Key。地址应是服务的接口根地址，例如 https://your-service.example/v1；具体协议与路径以服务说明为准。
2. 按需要设置请求超时和最大并发任务，确认「启用此连接」，点击 保存连接。
3. 点击 检查已保存连接。这一步只检查本地连接配置与凭据是否可用，不会向供应商发送请求或执行生成；检查通过还需要用实际任务确认服务是否支持所选模型。
4. 在「连接中的模型」填写服务提供的 服务端模型 ID 和显示名称，确认「启用此模型」，点击 保存模型。服务端模型 ID 必须与服务要求一致，显示名称可以自己取。
5. 图生视频模型需勾选 支持参考图片输入（图生视频）。需要默认参数时，在「模型参数」中填写 JSON 对象，不填写密钥或请求头。
6. 在「创作角色」为图片生成、视频生成、配音选择对应模型。手动生成仍可在面板中另选模型；协作制作使用这里的媒体角色配置。

生视频目前接入的是映流媒体网关 v1。普通厂商的视频 API 需要对应适配器，填写一个服务地址并不会自动转换协议。仓库没有提供公共网关地址，测试网关也不能作为日常生成服务。

API Key 通过 DSH 凭据服务保存，不写入工程或模型参数。密钥不会回显；输入框留空会保留原值，点击 清除密钥 才会删除。已有任务保存提交时的地址和模型配置，之后修改模型不会把旧任务切到新服务；仍被未结束任务使用的连接和模型会受到保护。

2. 生成并采用素材

1. 收起模型中心，选择「生成方式」：文字生成图片、文字生成视频 或 参考图片生成视频。
2. 选择「使用模型」，在「画面描述」中说明主体、环境、镜头运动、风格和需要保留的细节。
3. 在「采用时用于」选择目标镜头。选择 加入素材库，稍后安排 时，结果采用后只加入资产库。
4. 图生视频时，先选中本次参考图片，并勾选允许上传。指定镜头时，只能选择该镜头使用或参考的图片；需要其他图片时，先调整镜头的素材关联。
5. 按服务能力填写图片尺寸、视频时长、宽高或「本次生成参数」，点击 开始生成素材。留空的项目使用模型默认值或服务默认值。
6. 在右侧「生成任务」查看进度。任务完成下载和媒体检查后显示 待采用，点击 采用结果 才会更新工程。

生成成功和加入影片是两件事。 待采用的素材会先保留，不会自动覆盖当前镜头。采用图片后可继续调整画面；采用视频后可在镜头属性中修改片段，默认不保留原声。如果生成期间工程有修改，采用时会按当前已保存版本重新检查目标镜头，遇到冲突先处理提示。

图生视频每次最多发送 3 张图片，总计不超过 6 MiB，最长边不超过 4096 像素；插件还会检查实际图片数据。上传许可只针对本次明确选中的图片，不会把整个资产库一并发送。

3. 查看状态、停止等待和恢复

按钮或状态	实际含义
停止等待	暂停本机对这项任务的查询，远端可能继续运行
请求远端取消	向服务申请取消；只有收到确认取消的回执，才表示云端已经取消
恢复／重试获取	查询原任务，或重试下载、检查结果；不直接重新生成
提交结果待确认	服务可能已经接收请求，先查询或核对服务记录，不要反复重新提交
待采用	结果已经取回并通过媒体检查，等待加入当前工程
费用未知	服务没有给出可确认的费用，不表示免费

下载失败时，保留任务并使用 恢复／重试获取；视频任务可以重新查单取得新的下载地址。生图接口如果没有查单能力，提交回执丢失时需要先核对服务记录。已明确停止等待的任务在重启后保持暂停；程序退出导致的中断会保留记录并按恢复规则继续查询。

从 DSH 会话发起的媒体任务会有宿主任务 ID 和插件媒体任务 ID。终止宿主等待（job_kill）只结束本地观察，后续应使用媒体任务 ID 查询，或在工作台请求远端取消。

把视频片段加入镜头

导入已有视频

小文件可以通过 资产库 → 导入素材 选择。较大文件打开 模型与素材生成 → 从本地路径导入视频，填写当前电脑上的视频文件绝对路径，点击 导入本地视频。

视频导入需要 FFmpeg 和 ffprobe。插件先检查媒体，再生成固定帧率的 H.264 MP4 播放副本；原始文件也会留在工程中，因此需要为原件、副本和临时处理文件预留磁盘空间。

浏览器文件选择方式的视频上限为 32 MiB，本地路径导入的默认单文件上限为 512 MiB。原件和规范化副本都受大小限制，副本可能比原件更大；视频还需满足不超过 60 分钟、边长 8192 像素和 120 FPS 的限制。格式是否可用以实际媒体检查为准。

安排片段、裁剪和原声

1. 选中镜头，在右侧展开 视频片段，从「镜头主视频」选择已导入或已采用的视频。
2. 设置「裁入」和「裁出」，单位为源视频秒数；裁出留空表示使用到文件结尾。
3. 设置「播放速度」，当前有效范围为 0.25～4 倍。画面适应可选 填满画面 或 完整展示。
4. 在「视频原声」中选择 静音 或 保留原声，点击 保存视频片段。
5. 刷新预览，检查视频与文字、图形的关系，再根据需要调整镜头时长。

每个镜头使用一段主视频。镜头长于有效视频片段时，画面保留最后一帧，原声结束后保持静音；视频片段设置不会自动把所有镜头缩放成同一片长。

需要单独调整声音时，点击 提取原声为音轨，再到「声音与配音」编辑。如果同时保留片段原声和提取后的音轨，要检查是否重复播放。移除片段 只解除该镜头的主视频安排，素材仍保留在资产库。

代码画面可以在视频上叠加字幕与图形。若视频被整片背景遮住，检查镜头源码中的不透明全屏背景，再修改源码；导入视频不会自动重写原有代码。

使用协作制作

协作制作 把导演规划、画面制作、可选配音、可选关键帧视觉检查和工程合并串成固定流程。适合需要一次完成多个步骤，或围绕现有镜头继续制作的情况；分镜画布仍用于安排影片播放顺序。

1. 先在顶部选择 DSH 创作模型。如果要生成图片、视频或 Speech 配音，在模型中心为相应「创作角色」配置模型。
2. 打开 协作制作，填写「本次制作要求」，说明要做的内容、风格、旁白以及需要保留的部分。
3. 选择「制作范围」：全部镜头 或 当前选中镜头。空工程会先建立分镜与默认源码。
4. 选择「画面制作方式」：代码动画、生成图片与代码画面 或 生成视频与代码画面。图片、视频方式保留已有代码，便于继续叠加编辑。
5. 按需要勾选「生成配音」和「使用视觉模型检查关键帧」。视觉检查需要所选 DSH 模型支持图片，也需要允许本次发送检查帧；参考图片同样要逐项选择并授权。
6. 设置「最多生成任务数」，点击 开始协作制作，在右侧「制作流程」查看各步骤状态和检查意见。
7. 完成后刷新预览并播放全片。若显示 待采用，先确认当前工程，再点击 采用候选结果；启用视觉检查的流程会按当前版本重新检查后合并。

制作期间可以继续编辑。流程先准备候选画面、声音和源码，检查后再合并；如果工程已变化，会保留候选结果等待处理，不直接覆盖你的修改。空工程预先建立的初始分镜是一个单独保存的版本，即使后续步骤失败也会保留。

暂停流程 会停止本地流程并保留已经完成的产物；它不等同于取消远端媒体任务。恢复／重试 会复用已完成步骤。配音提交后若中断且无法确认结果，不会自动重复合成，需要先核对服务记录；明确失败后再次尝试可能产生新的生成费用。

当前没有可靠的全流程预报价。费用上限留空时可按任务数限制制作；填写金额上限后，流程会在调用模型前暂停，直到具备可确认的报价能力。界面显示的媒体费用也不能当作整片总费用。

视觉检查只会检查候选镜头的选定关键帧，最多 3 帧，不能代替完整播放、试听和人工检查。配音、字幕、镜头节奏和最终成片仍需按检查并导出中的方式确认。

添加配音、音乐和音效

导入音频后，需要把它添加为声音片段，才会进入影片。自动生成的镜头配音会直接添加到对应镜头。

使用已有音频

1. 在 资产库 → 导入素材 中选择音频文件。
2. 打开 声音与配音，选择「音频资产」和「用途」：配音、背景音乐或音效。
3. 选择「绑定范围」。旁白通常绑定具体镜头，背景音乐通常绑定整部影片。
4. 点击 添加声音片段，设置时间和音量。需要时勾选循环播放。
5. 确认 预览和导出包含声音 已勾选，切回 影片预览，点击 刷新预览 后播放试听。

参数	如何理解
片段起点（秒）	绑定镜头时，相对该镜头开头计算；绑定全片时，相对影片开头计算
裁入（秒）	从源音频的哪个位置开始使用
裁出（源文件秒）	使用到源音频的哪个位置；留空使用到文件结尾
音量	1 为原音量，0.25 为原音量的四分之一；可以先降低背景音乐，再试听旁白是否清楚
淡入、淡出（秒）	声音渐强、渐弱的持续时间

例如，把一段音频绑定第二个镜头，起点设为 1，裁入设为 2、裁出设为 6，就会在第二个镜头开始 1 秒后，播放源文件第 2～6 秒的内容。

根据文字生成配音

手动生成镜头配音的入口是 声音与配音 → 配音模型设置。协作制作也可以使用模型中心的 Speech 配音角色，两处配置的使用方式见下文。

使用 macOS 本机语音：

1. 语音端点填写 local:say，勾选「启用」。
2. 「声音」填写本机已安装的系统声音名称，例如已安装时可用的 Tingting；留空使用系统默认。无需填写配音模型或 API Key。
3. 设置语速，点击 保存配音配置。
4. 选中镜头，填写「镜头旁白」，点击 生成镜头配音。

使用自有语音服务：

在同一面板填写兼容语音接口的完整地址，例如 https://your-service.example/v1/audio/speech，并填写服务要求的模型 ID、声音 ID、语速和语音 API Key。勾选「启用」后保存配置，再生成镜头配音。地址、模型和声音 ID 以该服务的实际要求为准。

语音 Key 使用 DSH 凭据服务保存，不写入影片工程，也不自动复用聊天模型的 Key。输入框留空会保留原 Key；点击「清除密钥」才会删除。 本机语音不调用外部 API；使用远程服务时，旁白文本会提交给你填写的端点。

默认不启用自动配音。远程兼容接口是否可用、支持哪些声音，需要按所用服务确认。

协作制作使用的配音

如果已经在模型中心配置 Speech 连接与模型，请在「创作角色」中指定 配音，并在模型的默认参数中填写服务要求的音色，例如：

{
  "voice": "服务支持的音色 ID",
  "speed": 1
}

协作制作勾选「生成配音」后优先使用这个角色；未指定时，沿用「配音模型设置」中已启用的本机或远程服务。单独点击「生成镜头配音」仍使用原有配音设置，不会自动改用模型中心的配音角色。

旁白比镜头长时怎么办

默认情况下，较长的镜头旁白会在必要时延长对应镜头。如果必须保持原有片长，勾选 锁定镜头时长；超长时会提示差额，你可以缩短旁白、调整裁剪，或解除锁定。

绑定整部影片的旁白不会自动决定延长哪个镜头；如果超出全片时长，会提示错误，需要先延长镜头或裁剪音频。重新生成同一镜头的配音会替换其原配音片段，旧音频素材仍保留在资产库中。

检查画面并导出

1. 设置画幅、分辨率和帧率

点击工作台顶部显示比例、尺寸和 FPS 的规格按钮，打开 输出设定。

示例工程使用 16:9、1280 × 720、24 FPS；请根据实际用途选择规格。

设置	可选内容
画幅比例	16:9、9:16、1:1、4:5、4:3、3:4、21:9、16:10，或自定义宽高
分辨率	短边 480、720、1080、1440、2160 像素，或自定义尺寸
帧率	24、25、30、50、60 FPS，以及 24000/1001、30000/1001、60000/1001 或自定义分数帧率
编码质量	标准（CRF 18）、高质量（CRF 16）、更小文件（CRF 23）

分辨率按短边计算。例如，16:9 的 1080p 是 1920 × 1080，9:16 是 1080 × 1920，4:5 是 1080 × 1350。以面板中显示的实际像素尺寸为准。切换帧率会保留镜头的秒数，并重新计算整数帧。

2. 检查实际预览

点击 预览 或 刷新预览。预览运行项目中的实际 HTML、CSS、JavaScript 和素材。

• 播放全片，检查顺序、节奏、文字和声音。
• 使用「上一帧」「下一帧」，或输入全片帧号后点击「定位」。帧号从 0 开始。
• 选择镜头，查看首帧、中间帧和末帧等关键画面；需要时打开「大预览」。
• 点击 导出当前帧 PNG，保存某一帧供检查或交流。

导出前建议确认：素材已正确绑定，文字没有被裁切，旁白没有超出画面，声音开关和输出尺寸符合要求。

3. 导出并找到成片

1. 点击 导出视频。
2. 在 任务记录 查看进度。执行中的任务可以取消；失败时先查看错误信息和日志，处理后再重试。
3. 完成后打开 历史成片，点击 播放成片 或 打开文件 ↗。这里同时显示导出时的工程版本、尺寸、时长和文件位置。

输出格式为 H.264 MP4。启用声音且有可混合的音频片段时，音轨使用 AAC、48 kHz、双声道。成片保存在工程的 exports/<导出 ID>/ 目录中。

每次导出使用启动时已保存的工程版本。导出开始后继续编辑，不会改变正在导出的内容；旧成片也会保留。如果想导出刚完成的修改，需要启动一次新的导出。

管理影片和会话

找回和整理影片

在首页的 我的影片 中，可以按名称或目录搜索，打开工作台继续编辑。卡片的管理菜单提供「重命名」「复制工程」「归档」，已归档工程可在 已归档 中恢复。

• 复制工程：生成独立工程，包含当前镜头、源码和素材；不继承会话关联、原修改历史或历史成片。
• 归档：保留原工程目录，从正在创作的列表中移出；需要时可以恢复。
• 打开工程目录：输入已有工程目录的绝对路径，即包含 project.json 的文件夹。

关联已有会话

一个会话可以关联多部影片，但同一时间只有一部「当前工程」。界面会说明本次关联是否切换当前工程。

1. 在影片卡片或工作台点击 关联会话。
2. 按会话名称或工作区搜索，选择希望继续制作的会话。
3. 查看原当前影片和目标影片，确认后建立关联。之后通过 继续会话 返回对话。

一个影片也可以关联多个会话。模型调用视频工具时，如果没有明确指定工程，就使用该会话的当前工程。

浏览影片和切换当前工程是不同操作。 在首页筛选影片、打开工作台，都不会改变模型的制作目标。切换到另一部影片时，使用明确的关联操作，或界面提供的 设为当前工程并进入会话。

解除关联只移除指定会话与影片的关系，保留工程和聊天记录。解除当前工程后，不会自动选中另一部影片。若会话或使用其工程的子代理正在执行，请等当前回合结束后再切换。已经启动的导出仍使用原工程版本。

子代理与团队任务

会话选择器默认显示普通会话；勾选 显示子代理／团队任务 后，可查看宿主发现的相关任务。

能够使用视频工具的子代理和团队成员，默认沿委派关系使用最近上级的当前工程。需要单独制作时，可以给某个成员建立专属关联；普通分叉会话不会自动继承影片。插件使用 DSH 已有的代理与任务服务，不负责创建团队或为代理额外安装工具。

多个成员编辑同一影片时，适合按镜头、声音或检查任务分工。开发者应在写入前读取最新 revision，并提交 expectedRevision，避免覆盖其他成员的修改。关联规则、继承行为和工具示例见会话与代理制作说明。

保存、备份与恢复

参数、素材关联、音轨和画布修改会自动保存，离开前请确认顶部显示 已保存。源码编辑需要单独点击 保存源码。已保存的工程在重启 DSH 后仍可继续使用。

新工程默认保存在 ~/Documents/DSHVideoProjects。自定义存放位置可通过插件组合包的 baseDirectory 配置；环境面板用于配置本地工具路径，也可下调「视频文件上限（MiB）」。

影片工程/
├── project.json       # 工程信息、分镜、参数、文字素材和媒体引用
├── assets/            # 图片、音频、视频原件与规范化播放副本
├── shots/             # 各镜头的前端源码
├── .studio/           # 完整版本、修改历史和任务状态，备份时需要保留
├── runtime/           # 插件生成的运行页面、混音等文件
└── exports/           # 每次导出的成片、输入快照和检查结果

备份或搬运时，请复制整个工程目录，包括隐藏的 .studio/。 在新位置通过「打开工程目录」继续使用。已保存源码可以随工程搬运；尚未提交的源码草稿保存在 DSH 客户端本地存储中，应先保存或下载备份。

「修改历史」中的撤销和重做在重开工程后仍然有效，恢复旧内容会产生新的工程版本。「任务记录」会保留完成、失败、取消和中断状态；支持重试的任务会显示 以当前工程重试。重试使用当前已保存内容，并不接着旧任务的逐帧进度继续。配音需要明确重新生成。

新工程使用 v2 工程格式；0.6.0 可以读取并迁移旧版 v1 工程，旧程序不会写入不支持的 v2。升级前可先备份完整工程目录，后续编辑建议继续使用 0.6.0 或兼容 v2 的版本。

工程基目录另存 sessions.json（会话关系）、styles.json（风格库）、models.json（模型连接与角色）、media-tasks/（媒体生成任务）和 workflows/（协作流程）。这些内容不随单个影片目录自动搬运，API Key 则留在 DSH 凭据服务中。更换机器后需要重新配置连接与凭据、关联当地的会话；尚未完成的远端任务应先在原安装中处理。

插件通过完整工程目录保存和搬运影片，目前不承诺与独立版映流的工程包完整互通。

如需修改镜头代码，优先使用「前端源码」面板。直接改写工程目录中的源码文件不会自动替换插件保存的完整版本。

常见问题

遇到的情况	可以怎样处理
安装后找不到入口	在插件管理中确认已经启用并处于运行状态，再查找侧栏「映流 · 视频工作台」；如有接口缺失提示，按提示核对宿主服务
无法选择创作模型	先在 DSH 配置模型提供方与模型，再回工作台选择；会话内制作使用的是该会话的模型
「创建并生成分镜」不可用	先用「创建影片」进入工作台，选择创作模型，再点击「生成分镜」；主题不能为空
已生成分镜，但画面仍很基础	检查并调整分镜后，继续点击「生成画面」；分镜生成不会自动完成全部动画
图片或文字导入失败	检查格式和文件大小：单张图片上限为 20 MB，单份文字上限为 2 MB
视频导入提示过大或工具未就绪	大于 32 MiB 时改用「从本地路径导入视频」；检查 FFmpeg、ffprobe 和磁盘空间，原件与播放副本均需满足限制
模型中心没有可用的生图或生视频模型	先保存对应协议的连接，再保存服务端模型 ID，确认连接与模型均已启用；图生视频还需支持参考图片输入
连接检查通过，生成仍然失败	连接检查不执行生成；继续核对模型权限、参数和服务协议。生视频需要实现映流网关 v1，普通厂商地址不能直接替代
已生成素材，却没有加入影片	在「生成任务」确认处于「待采用」后点击「采用结果」；只加入素材库时，还需在镜头中安排
已停止等待，服务仍在生成	停止等待只暂停本地查询；需要时点击「请求远端取消」，并以服务确认状态为准
显示提交结果待确认	先恢复查询或核对服务端记录，不要重复点击生成；生图服务可能没有查单接口
协作制作设置费用上限后暂停	当前缺少全流程可靠报价，无法确认费用时会在调用前暂停；费用未知不表示免费
素材已导入，却没出现在画面中	图片、文字在「素材关联」设为「使用」，视频在「视频片段」选择主视频并保存；自定义源码也需要读取相应内容，且全屏背景可能遮住视频
改了文字、颜色或图片位置，预览没有变化	先点「刷新预览」；如仍无变化，检查自定义源码是否读取了对应的 ctx.params 参数
提示主链待连接，无法生成画面或导出	检查镜头顺序是否断开、分叉或循环；确认镜头条顺序后，可点「按镜头条连接」
提示有源码草稿，不能预览或导出	点「查看源码草稿」，保存或丢弃尚未提交的草稿后继续
显示保存冲突或 REVISION_CONFLICT	工程已被其他操作更新。如有未保存参数，先点击「保存本地参数副本」，再按提示重新读取最新工程，对照副本补回需要的改动；源码草稿会保留
实际帧检查或导出提示找不到工具	到「环境」检查 Chromium、FFmpeg、ffprobe；填写可执行文件的绝对路径，再点「保存并检查环境」
导入音频后，预览和成片没有声音	在「声音与配音」中添加声音片段，检查音量与「预览和导出包含声音」，再刷新预览
「生成镜头配音」不可用	先选中镜头并填写旁白，再在「配音模型设置」启用服务并保存配置
本机配音找不到声音	将「声音」留空使用系统默认，或改填本机已安装的声音名称
旁白超出镜头，或总片长变长	检查「锁定镜头时长」。可缩短旁白、裁剪音频或手动延长画面；未锁定时，镜头旁白可自动延长镜头
重启后任务显示已中断或暂停	本地渲染可按提示「以当前工程重试」；媒体任务使用「恢复／重试获取」，协作流程使用「恢复／重试」。提交结果不明的配音先核对服务记录
当前打开的影片与模型修改的影片不同	打开工作台只影响浏览。检查会话的「当前工程」，通过关联操作切换，或在会话中明确指定影片
成片无法在插件内播放	先用「打开文件 ↗」检查文件；若文件本身也异常，查看任务错误和日志，再重新导出

开发与扩展

以下命令在 yingliu-video-studio 插件目录中执行，面向需要构建、调试或扩展插件的开发者。按当前锁文件的依赖要求，使用 Node.js 22.18+（22.x）或 24.11+。

先安装锁文件中的开发依赖：

npm ci --legacy-peer-deps --ignore-scripts

本地测试还需要能解析 package.json 中的 DSH peer dependencies。上面的命令会跳过自动安装 peer dependencies；运行插件时这些依赖由 DSH 提供，单独测试时需要链接到官方宿主提供的依赖。可以复用已安装宿主的 node_modules，或在插件检出之外创建临时宿主目录，按以下步骤准备；将占位路径替换为自己的绝对路径：

npm install --prefix "<临时宿主目录>" --ignore-scripts --save-exact @deepseek-ai/dsh@latest
node scripts/link-host-dependencies.mjs "<临时宿主目录>/node_modules"

链接脚本会先核对所有 peer 包名与声明范围（包含预发布版本），DSH peers 接受任意发布版本，Cordis 保留内核范围，再建立目录链接；Windows 使用 junction。它不修改插件依赖声明或锁文件。也可通过 DSH_HOST_NODE_MODULES 指定宿主的 node_modules 目录。

依赖准备好后，执行检查、构建和打包：

DSH_HOST_NODE_MODULES="<宿主目录>/node_modules" npm run verify:compat
node -e "require('node:fs').mkdirSync('artifacts',{recursive:true})"
npm pack --pack-destination artifacts

构建会检查最终 lib/client.js 并执行其模块工厂，只允许宿主提供的 react 与 react/jsx-runtime 外部引用。LiteGraph、风格 ZIP 导入所需的 fflate 必须内联；DSH 浏览器加载器不会从 node_modules 查找普通 npm 包。若出现 require("fflate") missed the module table，请重建并安装修正后的包，仅向依赖或 dsh.client.inject 添加 fflate 无法解决该问题。可以用 node scripts/check-client-bundle.mjs 单独检查构建产物。

scripts/prepare-local.mjs 供维护者复用已有本地依赖，必须明确设置 DSH_REFERENCE_PLUGIN，指向已安装本插件全部开发与运行依赖的参考插件目录；宿主依赖默认来自参考目录的 .local/runtime/node_modules，也可用 DSH_HOST_NODE_MODULES 指定。脚本先检查来源，缺失时会停止并给出标准 npm 流程指引。新机器优先使用上述 npm 流程，无需个人目录、父仓库 Playwright 或本地 tar 包。

npm run preview 使用官方 DSH 运行库和独立 profile，默认端口为 19405。CLI 搜索顺序为显式 DSH_CLI、PATH 中的 dsh，最后是 macOS 的默认 .app 路径。显式路径无效时会报错；Windows npm 的 dsh.cmd 会转换为已核对官方包的 JS 入口，由 Node 直接执行。其他 .cmd/.bat 启动器请将 DSH_CLI 指向官方 lib/bin.js。目录链接在 Windows 使用 junction。预览脚本中的固定响应模型只用于源码测试，不参与已安装插件的运行；它不能用于判断真实模型的生成质量。

.github/workflows/platform-checks.yml 定义 Windows、macOS 和 Linux 的类型检查、测试与构建，分别使用固定基线宿主、npm latest 与 next 宿主，并调用官方兼容性判定器做版本矩阵回归。基础 CI 会记录媒体工具是否可用，媒体测试的跳过不能作为该平台导出通过的证据。Windows CI 先启用 Developer Mode 并实测文件及目录 symlink 权限；权限不足即失败。普通本地测试若缺少该权限会明确跳过真实 symlink 测试，也可设置 DSH_REQUIRE_SYMLINK_TESTS=1 要求失败。工作流定义不代表三平台已实际运行或原生界面已验收。

文档	内容
API 与场景接口	工程结构、视频工具、音轨、ctx 参数和源码渲染约定
会话与代理制作说明	多影片关联、子代理继承、团队协作和版本冲突处理
多模态制作说明	模型连接、持久媒体任务、上传授权、候选结果与协作流程
媒体网关 v1	视频服务协议、Schema 和请求／响应示例
0.6.0 验收说明	多模态功能的本地协议与媒体检查，以及尚未覆盖的验证
宿主兼容机制	接口检查、内核约束与官方兼容性判定
0.4 验收说明	历史版本的检查范围、复现方式与验收结果
操作系统适配进度	三系统基础实现、当前验证边界与剩余真机验收
配图来源	截图环境、演示素材和各张图片的内容
项目来源	插件与相关项目的关系
第三方声明	使用的开源组件和许可来源
GNU GPL v3.0 许可证（GPL-3.0-only）	本项目的使用许可

详细验证范围以对应版本的验收文档为准。0.6.0 多模态功能已记录本地测试网关、受控 DSH 接口与真实本地媒体检查；这些结果不等同于真实供应商生成成功，也不代表新增了原生 Desktop 或 Windows/macOS 安装验收。README 配图保留其原版本范围，真实服务的协议兼容、生成质量、费用和最终成片需要分别确认。

本项目采用 GPL-3.0-only，许可证与第三方组件声明见上表。

npm 包与源码

公开 npm 包名为 yingliu-video-studio，当前版本 0.6.0。在 DSH 插件管理中填写 yingliu-video-studio@0.6.0，或使用同版本 .tgz 文件安装。包名、客户端模块注册和 Cordis 引用已保持一致。升级原 dsh-video-studio 插件时，先停用旧包，再启用新包，避免同一宿主同时注册两套视频工作台；工程默认目录和既有编辑草稿的存储标识保持兼容。

发布包同时包含对应的 src/、types/、tests/、构建脚本和许可证。完整锁文件在本仓库中；源码检出使用上面的 npm ci 流程，直接从 npm 包源码重建时先运行 npm install --legacy-peer-deps --ignore-scripts，再链接官方宿主并执行构建。发布来源见 SOURCE.json 与 npm 的 gitHead。