# cutsdk 快速开始

## 1. 安装

```bash
npm install cutsdk
npx cutsdk init
```

## 2. 创建一个简单草稿

创建 `create-draft.ts`：

```ts
import { createAndRenderDraft } from 'cutsdk';

async function main() {
  const result = await createAndRenderDraft({
    draft: {
      version: '1.0',
      canvas: { width: 1080, height: 1920 },
      duration: '3s',
      tracks: [
        {
          type: 'text',
          clips: [
            {
              type: 'caption',
              text: '第一个 cutsdk 草稿',
              start: '0s',
              duration: '3s',
              position: 'center',
            },
          ],
        },
      ],
    },
    output: {
      draftsDir: process.env.CUT_DRAFTS_DIR,
      name: '第一个 cutsdk 草稿',
    },
    render: false,
  });

  console.log(result.draft.draftId);
  console.log(result.draft.filePath);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

用你的 TypeScript 运行器执行，例如：

```bash
npx ts-node create-draft.ts
```

执行后，打开终端输出的草稿目录，即可在剪映桌面端查看。

## 3. 添加媒体

使用 `assets` 定义可复用媒体，再在 clips 中引用：

```ts
import { createAndRenderDraft } from 'cutsdk';

await createAndRenderDraft({
  draft: {
    version: '1.0',
    canvas: { width: 1080, height: 1920 },
    duration: '5s',
    assets: {
      bg: { type: 'image', src: '/absolute/path/bg.png', width: 1080, height: 1920 },
      music: { type: 'audio', src: '/absolute/path/music.mp3', duration: '5s' },
    },
    tracks: [
      {
        type: 'visual',
        clips: [{ type: 'image', asset: 'bg', start: '0s', duration: '5s' }],
      },
      {
        type: 'audio',
        clips: [{ type: 'audio', asset: 'music', start: '0s', duration: '5s', volume: 0.7 }],
      },
      {
        type: 'text',
        clips: [{ type: 'caption', text: '图片 + 音乐 + 字幕', start: '0s', duration: '5s' }],
      },
    ],
  },
  output: { draftsDir: process.env.CUT_DRAFTS_DIR, name: '图片音乐字幕' },
  render: false,
});
```

## 4. 校验复杂 Spec

```ts
import { validateDraftSpec } from 'cutsdk';

const result = validateDraftSpec(spec);
if (!result.valid) {
  console.error(result.errors);
}
```

## 5. 时间规则

低层 API：

```ts
{ start: 0, end: 3000000 } // 3 秒
```

AI Draft Spec：

```ts
{ start: '0s', duration: '3s' }
```

## 6. 当前 Spec 限制

- 同一个 Spec 内，图片/视频 `transform` 会整批应用，不能每段素材独立设置不同 scale/position。
- 同一个 Spec 内，字幕 `style` 和 `position` 会整批应用，不能每条字幕完全不同位置样式。
- 需要逐片段差异化时，先用 Spec 创建主体，再用 `createAndRenderDraft` 的 `afterCreate` 或低层 SDK API 后处理。

## 7. CLI 本地路径与文字效果

```bash
cutcli draft easy <draftId> --audio-src ./素材/bgm.mp3 --image-src ./素材/bg.png \
  --text "爆款标题" --font-size 10 --text-color "#ffffff"

cutcli query text-effects --keyword 火焰 --limit 5
cutcli text add <draftId> --text "爆款标题" --start 0s --duration 3s \
  --text-effect "红黄火焰综艺花字" --shadow --shadow-color "#000000"
```

## 8. 云渲染状态

```bash
cutcli cloud render <draftId> --wait --pretty
cutcli cloud result <jobId> --pretty
```

状态 `0/1/2` 表示等待或处理中；`3/5/6` 表示失败终态；只有 `7` 表示成功，此时才会有 `video_url`。