@happyvertical/smrt-video

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.5万

Video content management for AI-powered video production in the SMRT ecosystem

原始使用文档
文档目录8 节
  1. Installation
  2. Usage
  3. API
  4. Models
  5. Key Types
  6. Design Principle
  7. Asset Ownership
  8. Dependencies

@happyvertical/smrt-video

Video production pipeline for AI-powered video generation in the s-m-r-t ecosystem. Models characters, performers, scenes, shots, sequences, compositions, and ComfyUI workflow templates.

Installation

pnpm add @happyvertical/smrt-video

Usage

import {
  Character,
  Performer,
  Scene,
  VideoShot,
  VideoSequence,
  VideoComposition,
  VideoShotCharacter,
  VideoWorkflow,
} from '@happyvertical/smrt-video';
import { Asset } from '@happyvertical/smrt-assets';

// Character = role being played (outfit, voice, branding)
const anchor = new Character({
  name: 'Bentley News Anchor',
  voiceProfileId: 'voice-123',
});
await anchor.save();

const seedImage = new Asset({
  name: 'Anchor Seed',
  sourceUri: 'file:///tmp/anchor-seed.png',
  mimeType: 'image/png',
});
await seedImage.save();
await anchor.addAsset(seedImage, 'seed-image');

// Performer = physical likeness for IP-Adapter face consistency
const performer = new Performer({ name: 'Alex', ipAdapterWeight: 0.85 });

// Scene = virtual background (image, video, or 360 panorama)
const studio = new Scene({
  name: 'News Studio',
  sourceType: 'image',
  projection: 'flat',
});

// Hierarchy: Composition -> Sequence -> Shot -> ShotCharacter
const composition = new VideoComposition({
  title: 'Evening News - March 2, 2026',
  fps: 30,
  width: 1920,
  height: 1080,
});
await composition.save();

const shot = new VideoShot({
  scriptText: 'Welcome to the evening news broadcast.',
  targetDuration: 30,
});
await shot.save();
// Estimated speech duration: scriptWordCount / 2.7 words per second
shot.estimatedDuration; // ~2.2 seconds
await shot.addAsset(seedImage, 'thumbnail');

// ComfyUI workflow with dynamic parameter injection
const workflow = new VideoWorkflow({
  name: 'Wan 2.6 + EchoMimic',
  workflowType: 'broadcast',
  workflowJson: comfyuiApiJson,
  nodeMapping: { seedImage: '1', audioFile: '5', outputVideo: '12' },
  requiredModels: ['wan_2.6_t2v_14b_fp8', 'echomimic_v2'],
});
await workflow.save();

// Inject runtime parameters into a deep-cloned workflow
const injected = workflow.injectParameters({
  seedImage: '/path/to/anchor.png',
  audioFile: '/path/to/tts.wav',
});

API

Models

ExportDescription
CharacterVirtual persona: seed image + voice profile + branding kit
PerformerPhysical likeness for IP-Adapter FaceID consistency
SceneVirtual background with viewpoints, lighting, and anchor points
VideoShotAtomic generation unit (extends Content) with script and frame duration
VideoShotCharacterJunction: shot-to-character with role (primary/secondary/background)
VideoSequenceThematic section (extends Content) with transition type and ordering
VideoCompositionTop-level container (extends Content): fps, resolution, render status
VideoWorkflowComfyUI template with node mapping for parameter injection
CompositeJobTracks a multi-step video generation job

Collections: CharacterCollection, VideoCompositionCollection, VideoSequenceCollection, VideoShotCollection, VideoShotCharacterCollection.

Canonical owned asset joins:

  • CharacterOwnedAsset -> character_assets
  • PerformerOwnedAsset -> performer_assets
  • SceneOwnedAsset -> scene_assets
  • VideoShot, VideoSequence, and VideoComposition inherit Content asset helpers backed by content_assets

Legacy STI asset subclasses CharacterAsset, PerformerAsset, SceneAsset, VideoCompositionAsset, VideoSequenceAsset, and VideoShotAsset remain readable during migration, but new writes should go through the model helpers. Provision the new join tables with smrt db:migrate before relying on canonical writes. Reads still fall back to legacy fields / STI rows when the new tables are not present yet.

Key Types

ExportDescription
CharacterStatuspending, ready
BrandingConfigLogo, colors, fonts, lower-thirds, ticker settings
WorkflowTypeprebake, broadcast, lipsync, postprod, custom
NodeMappingMaps semantic names (seedImage, audioFile, etc.) to ComfyUI node IDs
RenderStatusdraft, rendering, ready, failed
VideoShotStatusdraft, queued, processing, ready, failed, published
TransitionTypenone, fade, slide, wipe
VideoMetadataDuration, resolution, codec, fps, word timings
SceneSourceTypeimage, video, panorama_360, panorama_180
VideoShotCharacterRoleprimary, secondary, background

Design Principle

Store frames, compute seconds. All duration fields use durationInFrames; convert with frames / fps. Speech duration estimated at 2.7 words/second (+/- 15% tolerance).

Asset Ownership

Character, Performer, and Scene expose getAssets(), getAssetByRole(), addAsset(), and removeAsset() on canonical noun-join tables. They continue to read legacy scalar slots and legacy STI asset rows during migration.

VideoShot, VideoSequence, and VideoComposition inherit the same helpers from Content, so their canonical ownership table is content_assets rather than a video-specific join table.

Dependencies

  • @happyvertical/smrt-core -- ORM and code generation
  • @happyvertical/smrt-assets -- base asset management
  • @happyvertical/smrt-config -- configuration loading
  • @happyvertical/smrt-content -- content models (VideoShot/Sequence/Composition extend Content)
  • @happyvertical/smrt-profiles -- profile references for characters
  • @happyvertical/smrt-tenancy -- multi-tenant scoping
  • @happyvertical/smrt-voice -- voice profile references

版本与发布记录

@happyvertical/smrt-video 共发布 365 个版本,首次发布于 2026/06/23;过去 12 个月发布了 365 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-video 的常见问题

@happyvertical/smrt-video 是什么?

Video content management for AI-powered video production in the SMRT ecosystem

如何安装 @happyvertical/smrt-video?

在项目目录运行 npm install @happyvertical/smrt-video,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-video 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-video 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-video 可以商用吗?

@happyvertical/smrt-video 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-video 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-video 在 2026/10/17 – 2026/11/15 这 30 天内被下载 15,398 次,日均约 513 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-video 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 365 个版本,其中过去 12 个月发布了 365 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。