@remixmate/template-core 1.3.0

package/API.md

@@ -0,0 +1,167 @@
+# @remixmate/template-core@1.3.0 API 速查
+
+> 由 `dist/index.d.ts` 自动生成，请勿手改。完整签名与 JSDoc 以包内 d.ts 为准。 共 52 个运行时导出、45 个类型导出。
+
+## 组件 / Components
+
+- `AudioLayer`
+  - `const AudioLayer: React.FC<AudioLayerProps>`
+- `Background`
+  - `const Background: React.FC<BackgroundProps>`
+- `DigitalHumanLayer` — 数字人视频图层。
+  - `const DigitalHumanLayer: React.FC<DigitalHumanLayerProps>`
+- `DigitalHumanPoster` — 封面用的静态数字人：有 posterSrc 时按同一个盒子画图，否则不渲染。
+  - `const DigitalHumanPoster: React.FC< …`
+- `GridParticleBackground`
+  - `const GridParticleBackground: React.FC<GridParticleBackgroundProps>`
+- `ReservedContentScaler` — layout=reserve 时把按固定宽度排版的内容整体等比缩进剩余区域。
+  - `const ReservedContentScaler: React.FC< …`
+- `SceneBackgroundLayer`
+  - `const SceneBackgroundLayer: React.FC<SceneBackgroundLayerProps>`
+- `SceneTransition`
+  - `const SceneTransition: React.FC<SceneTransitionProps>`
+- `SubtitleBar`
+  - `const SubtitleBar: React.FC<SubtitleBarProps>`
+- `TextLayer`
+  - `const TextLayer: React.FC<TextLayerProps>`
+- `TimelineSequencer`
+  - `const TimelineSequencer: React.FC<TimelineSequencerProps>`
+
+## Hooks
+
+- `useActiveSubtitle` — Return the subtitle text currently active at the playhead, or an empty string if none. Pure data hook — visual rendering is each template's responsibility (so templates can style the subtitle bar f...
+  - `function useActiveSubtitle(segments: SubtitleSegment[]): string`
+- `useActiveSubtitleIndex` — Return the index of the currently active segment (scene-local frames), or -1 if none. Useful when a template wants to link subtitle progress to on-screen element highlighting.
+  - `function useActiveSubtitleIndex(segments: SubtitleSegment[]): number`
+- `useAssetUrl` — Resolve an assetId to a playable URL (or local file path for public/). Returns null when the asset is unknown.
+  - `function useAssetUrl(assetId: string | undefined, resolvedAssets: ResolvedAsset[]): string | null`
+- `useCanvasScale` — Scale factor for px constants authored against a 1920px long edge.
+  - `function useCanvasScale(): number`
+- `useLocalSubtitles` — Hook 版本 —— 结果按 (segments, startFrame, leadFrames) 记忆化。
+  - `function useLocalSubtitles(entry: Pick<TimelineEntry, "subtitleSegments" | "startFrame">, options?: LocalizeSubtitlesOptions): SubtitleSe...`
+
+## 函数 / Functions
+
+- `chunkSubtitleSegments` — 把字幕段数组展开成「屏」数组。不需要切的段原样透传（同一个对象引用）。
+  - `function chunkSubtitleSegments(segments: SubtitleChunk[], options: ChunkSubtitleOptions): SubtitleChunk[]`
+- `displayWidth` — 文本的显示宽度，单位是「全角字」。
+  - `function displayWidth(text: string): number`
+- `estimateLineCapacity` — 从排版参数估算一行放得下多少个全角字。
+  - `function estimateLineCapacity(availableWidthPx: number, fontSizePx: number, letterSpacingPx?: number): number`
+- `fontStack` — Normalise a metadata font value into a valid CSS `font-family` stack.
+  - `function fontStack(font?: string): string`
+- `grainDataUri` — `noise` preset 的胶片颗粒。
+  - `function grainDataUri(blend: SceneBackgroundNoiseBlend): string`
+- `isLegacyAvatarInput` — 旧版 image-slide 形态：只给了 `avatarAssetId`，没有任何新字段。 image-slide 据此走与改动前逐像素一致的 legacy 版式。
+  - `function isLegacyAvatarInput(input: DigitalHumanInput): boolean`
+- `localizeSubtitles` — 纯函数版本 —— 可在循环 / 非组件上下文 / 测试里调用。
+  - `function localizeSubtitles(entry: Pick<TimelineEntry, "subtitleSegments" | "startFrame">, options?: LocalizeSubtitlesOptions): SubtitleSe...`
+- `mergeDigitalHumanConfig` — 合并外观配置。优先级：`digitalHuman.*` > `avatarPosition / avatarScale` > 模板默认 > 内置默认。
+  - `function mergeDigitalHumanConfig(config: DigitalHumanConfig, defaults: DigitalHumanDefaults, dsl?: …`
+- `pickDigitalHumanInput` — 从 `entry.props` 收集数字人输入。
+  - `function pickDigitalHumanInput(props: unknown): DigitalHumanInput`
+- `reportDigitalHumanIssues` — 上报解析阶段收集到的问题。模板在决定是否渲染之前调用， 这样即便数字人最终不显示（素材解析失败）也会留下诊断。
+  - `function reportDigitalHumanIssues(dh: ResolvedDigitalHuman, box: DigitalHumanBox | null, templateId: string, sceneId?: string): void`
+- `reportSceneDegraded`
+  - `function reportSceneDegraded(report: SceneDegradedReport): void`
+- `resetSceneDegradedReports` — 测试专用：清空去重表。
+  - `function resetSceneDegradedReports(): void`
+- `resolveActiveChunk` — 当前帧该显示哪一屏。
+  - `function resolveActiveChunk<T extends SubtitleChunk>(chunks: T[], frame: number, holdFrames: number): T | undefined`
+- `resolveAsset` — Return the full ResolvedAsset (or undefined). Useful when the template needs `type`, `duration`, or other metadata in addition to the URL.
+  - `function resolveAsset(assetId: string | undefined, resolvedAssets: ResolvedAsset[]): ResolvedAsset | undefined`
+- `resolveAssetUrl` — Non-hook variant for use inside loops / .map callbacks.
+  - `function resolveAssetUrl(assetId: string | undefined, resolvedAssets: ResolvedAsset[]): string | null`
+- `resolveChunkFadeOpacity` — 换屏时文字的淡入不透明度（0–1）。
+  - `function resolveChunkFadeOpacity(framesIntoChunk: number): number`
+- `resolveDigitalHuman` — 从 props 解析出这一屏的数字人。
+  - `function resolveDigitalHuman(props: unknown, resolvedAssets: ResolvedAsset[], options: ResolveDigitalHumanOptions): ResolvedDigitalHuman`
+- `resolveDigitalHumanBox` — 计算盒子。
+  - `function resolveDigitalHumanBox(config: ResolvedDigitalHumanConfig, canvas: Canvas, options?: …`
+- `resolveReservedRegion` — 内容让位（layout=reserve）：返回让出数字人一侧后剩余的水平区间（px）。 盒子居中（side=none）时不让位，返回整幅。
+  - `function resolveReservedRegion(box: DigitalHumanBox | null, canvas: Canvas, gap?: number): …`
+- `resolveRunFadeOpacity` — 整条字幕 run 的淡入淡出不透明度（0–1），头尾各淡 `capFrames` 帧。
+  - `function resolveRunFadeOpacity(frame: number, runStart: number, runEnd: number, capFrames: number): number`
+- `resolveSceneBackground` — 纯函数版的 preset 解析 —— 把「给定 background 该画哪些层」的判断独立出来， 便于单测，也让组件本体只负责把结果摆成 DOM。
+  - `function resolveSceneBackground(background: SceneBackground | undefined, signaturePreset: string, defaultMediaMotion?: BackgroundMotion, ...`
+- `resolveSubtitleBottomPx` — Resolve the caption's distance from the bottom edge, in px.
+  - `function resolveSubtitleBottomPx(mode: ResolvedSubtitleMode, canvas: …`
+- `resolveSubtitleMaxWidthPct` — 字幕让位：居中的字幕在 [bandTop, 画面底] 这条带子里，数字人与之有交叠且偏在 一侧时，收窄字幕最大宽度（仍居中），让两侧都不碰到盒子。
+  - `function resolveSubtitleMaxWidthPct(box: DigitalHumanBox | null, canvas: Canvas, opts: …`
+- `resolveSubtitleMode` — Pick the concrete mode to render.
+  - `function resolveSubtitleMode(mode?: SubtitleMode, captionStyle?: "pill" | "stroke", backgroundLuma?: number): ResolvedSubtitleMode`
+- `sanitizeDiagnosticSrc` — 把一个媒体地址压成可以进日志的形态：去掉签名 query 与 hash，data URI 只保留 `data:image/png` 这样的前缀（正文可能有几百 KB）。
+  - `function sanitizeDiagnosticSrc(src: string): string`
+- `sanitizeDigitalHumanConfig` — 校验 `customPayload.digitalHuman`：枚举不合法的丢弃、数值越界的钳制， 类型不对的丢弃。未知字段忽略（不报）。
+  - `function sanitizeDigitalHumanConfig(raw: unknown): SanitizedDigitalHumanConfig`
+- `sentenceStartFrames` — 每**句**旁白的起拍帧 —— 给"第 i 个动作对齐第 i 句"的模板用。
+  - `function sentenceStartFrames(segments: readonly SubtitleSegment[]): number[] | null`
+- `splitSubtitleText` — 把一条字幕文本切成若干屏，并去掉每片的行尾标点。
+  - `function splitSubtitleText(text: string, options: SplitSubtitleOptions): string[]`
+- `spokenWeight` — 文本的**口播权重**，单位近似「音节」。片内时间按它分配，不用 `displayWidth`。
+  - `function spokenWeight(text: string): number`
+
+## 常量 / Constants
+
+- `DEFAULT_DIGITAL_HUMAN_ASPECT` — 没有显式宽高比、也没有视频元数据时的缺省宽高比（竖版半身）。
+  - `const DEFAULT_DIGITAL_HUMAN_ASPECT: number`
+- `DEFAULT_MIN_CHUNK_UNITS` — 碎片下限的默认值：切出来短于它的片并回相邻片，避免闪过一个「的延迟」。
+  - `const DEFAULT_MIN_CHUNK_UNITS = 7`
+- `DEFAULT_SPLIT_MAX_UNITS` — 单屏目标上限的默认值。
+  - `const DEFAULT_SPLIT_MAX_UNITS = 20`
+- `DIGITAL_HUMAN_ANCHORS`
+  - `const DIGITAL_HUMAN_ANCHORS: readonly DigitalHumanAnchor[]`
+- `DIGITAL_HUMAN_PROP_KEYS` — props 里与数字人有关的全部键。多版式模板据此把它们当 frame 级字段。
+  - `const DIGITAL_HUMAN_PROP_KEYS: readonly ["digitalHuman", "avatarAssetId", "avatarPosition", "avatarScale", "avatarOffsetFrames", "avatarS...`
+- `DIGITAL_HUMAN_SIZE_PRESETS` — 尺寸档位：盒高 / 画面短边。
+  - `const DIGITAL_HUMAN_SIZE_PRESETS: Record<DigitalHumanSizePreset, number>`
+- `LINE_FILL_LIMIT` — 单屏最多占一行容量的多少。
+  - `const LINE_FILL_LIMIT = 0.9`
+
+## 类型 / Types
+
+- `BackgroundMotion`
+- `BgmConfig`
+- `ChunkSubtitleOptions`
+- `CompositionManifestEntry` — Describes a single entry in the generated COMPOSITION_MANIFEST. The manifest maps a compositionId (e.g. "ImageSlideOpening") to the React component that should render it, along with the template it...
+- `DigitalHumanAnchor`
+- `DigitalHumanBox` — 画面上的像素盒子。
+- `DigitalHumanConfig` — `customPayload.digitalHuman` —— 作者可写的外观配置，全部可选。
+- `DigitalHumanDefaults` — 模板默认值：每个模板可以有自己的默认位置 / 大小 / 形状。
+- `DigitalHumanEnter`
+- `DigitalHumanInput` — 从 props 里收集到的原始输入（尚未校验）。
+- `DigitalHumanInsets` — 安全区内缩（px）。例如黑板模板的木框、字幕带。
+- `DigitalHumanLayerProps`
+- `DigitalHumanLayout`
+- `DigitalHumanOnEnd`
+- `DigitalHumanPosition`
+- `DigitalHumanSegmentRole` — 本场景在所属连续段里的位置。段长为 1 时是 `only`。
+- `DigitalHumanShape` — 数字人（口播 talking-head 视频）叠加层的数据契约。
+- `DigitalHumanSizePreset`
+- `GridParticleBackgroundProps`
+- `GridParticleConfig` — DSL 里 `customPayload.background` 的形状（与模板 schema 同名字段）。
+- `GridParticleTheme` — 本组件读取的主题字段。颜色都是 `"r,g,b"` 三元组，便于拼 rgba。
+- `GridParticleTuning` — 按版面调的几何参数。不同模板的文字 / 舞台位置不同，暗角和柔光带要跟着挪。
+- `Layer`
+- `LocalizeSubtitlesOptions` — 把 RenderPlan 里的**全片绝对帧**字幕时间码平移成**场景局部帧**。
+- `MainVideoProps`
+- `RenderConfig`
+- `ResolvedAsset`
+- `ResolvedDigitalHuman`
+- `ResolvedDigitalHumanConfig` — 校验、合并默认值之后的外观配置 —— 每个字段都有确定值。
+- `ResolveDigitalHumanOptions`
+- `ResolvedSubtitleMode` — Resolved modes — everything `auto` can collapse into.
+- `SanitizedDigitalHumanConfig`
+- `SceneBackground` — 场景背景的声明。
+- `SceneBackgroundLayerProps`
+- `SceneBackgroundNoiseBlend` — `noise` preset 的混合模式。见各模板 theme 里 noiseBlend 的注释。
+- `SceneBackgroundSlotContext` — 传给 `signature` / `depth` 插槽的上下文。
+- `SceneDegradedReport` — 模板降级诊断 —— `template.scene.degraded` 的唯一发射点。
+- `SplitSubtitleOptions`
+- `SubtitleChunk` — 一屏字幕。帧号与来源 `SubtitleSegment` 同基准（场景局部帧）。
+- `SubtitleMode` — Subtitle presentation modes.
+- `SubtitleSegment`
+- `TemplateCompositionProps` — Every template Composition component must implement this function signature.
+- `TimelineEntry` — A single scene on the timeline. The `props` field is an opaque container — each template parses it into its own strongly-typed interface. Core does NOT know what fields any given template expects.
+- `TimelineSequencerProps` — 时间轴派发器 —— 把 timeline 的每个 entry 按 compositionId 解析成模板组件， 包进 Remotion Sequence，再叠加可选的全局 BGM。
+- `Typography`

package/LICENSE

@@ -0,0 +1,85 @@
+RemixMate Template SDK License
+Version 0.1 (DRAFT — pending legal review / 草案，待法务审阅)
+
+Copyright (c) 2026 RemixMate. All rights reserved.
+
+本许可适用于 @remixmate/template-core、@remixmate/template-starter 及 starter 随附的
+示例模板（以下合称"本 SDK"）。中文与英文文本具有同等效力；如有歧义，以中文文本为准。
+
+一、授权
+您可以下载、安装、在本地运行（包括使用 Remotion Studio 预览）本 SDK，并修改示例模板，
+但仅限于开发、测试将在 RemixMate 平台上渲染的视频模板这一目的。
+
+二、限制
+1. 不得在 RemixMate 平台之外使用本 SDK 渲染并对外分发视频成品，也不得将本 SDK 作为任何
+   视频生成或渲染服务的组成部分。
+2. 不得单独再分发本 SDK 或其中的示例模板；作为您的模板的一部分上传到 RemixMate 平台除外。
+3. 不得反编译、反向工程或以其他方式还原 template-core 的源代码，也不得利用本 SDK 或
+   RemixMate 平台的渲染能力提取平台模板或他人模板的源代码。
+4. 不得移除或修改本许可及版权声明。
+
+三、您的模板
+您自己编写的模板代码归您所有。您授予 RemixMate 为向您提供渲染服务所必需的、非独占的
+托管、处理与渲染许可。基于示例模板修改而来的模板中，示例原有的内容仍归 RemixMate 所有。
+
+四、终止
+违反本许可任一条款，授权自动终止。若您在收到 RemixMate 通知后 30 日内纠正违约行为，
+授权恢复；同一许可下再次违约的，不再给予纠正期。
+
+五、免责与责任限制
+本 SDK 按"现状"提供，不附带任何明示或默示的担保，包括适销性、特定用途适用性与不侵权。
+在法律允许的最大范围内，RemixMate 对因使用本 SDK 产生的任何损失不承担责任；如法律要求
+承担责任，责任总额以您在过去 12 个月内为 RemixMate 平台服务实际支付的费用为上限。
+
+六、与平台服务条款的关系
+本许可与 RemixMate 服务条款并行适用。渲染、计费、内容合规等事项以服务条款为准。
+本许可新版本发布后，新版本适用于此后获取的 SDK 版本。
+
+七、第三方组件
+本 SDK 依赖的 Remotion（https://www.remotion.dev）有其独立许可：个人与小团队免费，
+达到一定规模的公司需要购买授权。您在本地使用 Remotion 属于您与 Remotion 之间的关系，
+条款以 Remotion 官方为准。
+
+--------------------------------------------------------------------------------
+
+RemixMate Template SDK License (English)
+
+This license covers @remixmate/template-core, @remixmate/template-starter and the
+example templates shipped with the starter (together, the "SDK").
+
+1. Grant. You may download, install and run the SDK locally (including previewing in
+   Remotion Studio) and modify the example templates, solely to develop and test video
+   templates that will be rendered on the RemixMate platform.
+
+2. Restrictions. You may not:
+   (a) use the SDK to render and distribute videos outside the RemixMate platform, or use
+       it as part of any video generation or rendering service;
+   (b) redistribute the SDK or the example templates on their own, except as part of your
+       template uploaded to the RemixMate platform;
+   (c) decompile, reverse engineer or otherwise reconstruct the source code of
+       template-core, or use the SDK or the RemixMate rendering service to extract the
+       source code of platform templates or other users' templates;
+   (d) remove or alter this license or any copyright notice.
+
+3. Your templates. Template code you write yourself belongs to you. You grant RemixMate a
+   non-exclusive license to host, process and render it as needed to provide the
+   rendering service to you. In templates derived from the examples, the original example
+   content remains owned by RemixMate.
+
+4. Termination. Your license ends automatically if you breach any term. It is reinstated
+   if you cure the breach within 30 days after notice from RemixMate; a second breach
+   under this license gets no cure period.
+
+5. No warranty; limitation of liability. The SDK is provided "as is", without warranty of
+   any kind. To the maximum extent permitted by law, RemixMate is not liable for any loss
+   arising from use of the SDK; where liability cannot be excluded, it is capped at the
+   fees you paid for RemixMate platform services in the preceding 12 months.
+
+6. Platform terms. This license applies alongside the RemixMate Terms of Service, which
+   govern rendering, billing and content compliance. A new version of this license applies
+   to SDK versions obtained after its release.
+
+7. Third-party components. Remotion (https://www.remotion.dev) has its own license: free
+   for individuals and small teams, while companies above a certain size need a paid
+   license. Your local use of Remotion is between you and Remotion; Remotion's official
+   terms apply.

package/README.md

@@ -0,0 +1,18 @@
+# @remixmate/template-core
+
+RemixMate 视频模板 SDK 的运行时与类型定义（编译产物，不含源码）。用它开发的模板在 RemixMate 平台渲染出片。
+
+- 起步：`remixmate template init my-templates`（会安装本包与 `@remixmate/template-starter`）
+- API 速查：见包内 `API.md`；完整签名与说明见 `dist/index.d.ts`
+- 运行环境：React 18、Remotion 4.0.446（与平台渲染服务一致）
+
+## 许可
+
+本包以「RemixMate Template SDK License」发布（见 `LICENSE`），不是开源许可。白话摘要：
+
+- 可以在本地安装、运行、预览，用来开发将在 RemixMate 平台渲染的模板；
+- 不可以在 RemixMate 之外用它渲染并分发视频，或把它嵌进其它视频服务；
+- 不可以单独再分发、反编译本包，或借渲染提取平台 / 他人模板的源码；
+- 你自己写的模板归你所有。
+
+Remotion 有独立许可（个人与小团队免费，达到一定规模的公司需购买授权），以 Remotion 官方条款为准。