tiktok-music-archive-downloader

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TikTok Music Archive Downloader

TikTok音乐档案下载工具

Follow shared release-shell rules in:

```
postplus-shared
```
release-shell rules

Use this skill when TikTok music or sound candidates have already been selected and the user needs local files.

Good fits:

"把这些 sound 的代表视频下下来"
"从 TikTok 视频里抽音频做参考"
"给这批 trending music 建本地素材库"
"下载样本并保留来源 manifest"

Do not use this skill for:

discovering trending music
collecting metadata from hosted collection
deciding whether an audio is legally usable for public posting

请遵循

postplus-shared

中的共享发布shell规则：

```
postplus-shared
```
发布shell规则

当已选定TikTok音乐或音效候选内容，且用户需要本地文件时，可使用此技能。

适用场景：

"把这些 sound 的代表视频下下来"
"从 TikTok 视频里抽音频做参考"
"给这批 trending music 建本地素材库"
"下载样本并保留来源 manifest"

不适用场景：

发现热门音乐
从托管集合中收集元数据
判断音频是否可合法用于公开发布

Read First

必读事项

Shared chain:
```
postplus-shared
```
TikTok music workflow

共享流程：
```
postplus-shared
```
TikTok音乐工作流

Source Skills

上游技能

Expected inputs usually come from:

../tiktok-music-sound-collector/SKILL.md

```
../tiktok-research/SKILL.md
```

预期输入通常来自：

../tiktok-music-sound-collector/SKILL.md

```
../tiktok-research/SKILL.md
```

Downloader

下载工具

Use the shared TikTok downloader:

bash

node ${CLAUDE_SKILL_DIR}/_postplus_shared/00-core/shared-runtime/scripts/download_videos_from_manifest_with_ytdlp.mjs \
  --manifest <download-manifest.json> \
  --output-dir <videos-dir> \
  --report <download-report.json> \
  --concurrency 2 \
  --attempts 3

The manifest should contain:

json

{
  "items": [
    {
      "sourceId": "musicid-videoid",
      "sourceUrl": "https://www.tiktok.com/@user/video/123"
    }
  ]
}

When the upstream normalized dataset includes both

postPageUrl

and direct video fields, prefer the canonical TikTok post page URL for

sourceUrl

. That keeps

yt_dlp

on the stable page surface instead of an expiring CDN URL.

使用共享的TikTok下载工具：

bash

node ${CLAUDE_SKILL_DIR}/_postplus_shared/00-core/shared-runtime/scripts/download_videos_from_manifest_with_ytdlp.mjs \
  --manifest <download-manifest.json> \
  --output-dir <videos-dir> \
  --report <download-report.json> \
  --concurrency 2 \
  --attempts 3

清单应包含以下内容：

json

{
  "items": [
    {
      "sourceId": "musicid-videoid",
      "sourceUrl": "https://www.tiktok.com/@user/video/123"
    }
  ]
}

当上游标准化数据集同时包含

postPageUrl

和直接视频字段时，优先选择标准TikTok帖子页面URL作为

sourceUrl

。这样能让

yt_dlp

基于稳定的页面而非过期的CDN URL进行操作。

Audio Extraction

音频提取

After videos are downloaded, extract audio with

ffmpeg

Prefer

m4a

for compact review assets:

bash

ffmpeg -y -i <video.mp4> -vn -c:a aac -b:a 192k <audio.m4a>

Use

wav

only when a downstream model or editor needs uncompressed audio:

bash

ffmpeg -y -i <video.mp4> -vn -ac 1 -ar 48000 <audio.wav>

视频下载完成后，使用

ffmpeg

提取音频。

对于紧凑的审阅素材，优先选择

m4a

格式：

bash

ffmpeg -y -i <video.mp4> -vn -c:a aac -b:a 192k <audio.m4a>

仅当下游模型或编辑器需要未压缩音频时，才使用

wav

格式：

bash

ffmpeg -y -i <video.mp4> -vn -ac 1 -ar 48000 <audio.wav>

Archive Layout

档案布局

Use a stable layout:

text

<work-folder>/.postplus/tiktok-music-archive-downloader/<run-id>/
  manifest/
    download-manifest.json
    download-report.json
  videos/
  audio/
  index.json

index.json

should link every local file back to:

```
musicId
```
```
musicTitle
```
```
sourceVideoUrl
```
```
sourceCollectionPath
```
local video path
local audio path
download status

使用稳定的目录结构：

text

<work-folder>/.postplus/tiktok-music-archive-downloader/<run-id>/
  manifest/
    download-manifest.json
    download-report.json
  videos/
  audio/
  index.json

index.json

应将每个本地文件关联到以下信息：

```
musicId
```
```
musicTitle
```
```
sourceVideoUrl
```
```
sourceCollectionPath
```
本地视频路径
本地音频路径
下载状态

Verification

验证

Before reporting success:

confirm downloaded files exist and are non-empty
confirm audio files exist and are non-empty
report failures separately instead of hiding them
keep source URLs in the manifest even when download fails

在报告成功前，请完成以下检查：

确认下载的文件存在且非空
确认音频文件存在且非空
单独报告失败情况，而非隐藏
即使下载失败，也要在清单中保留源URL

Handoff

交接

Need video-level breakdown: run a dedicated visual analysis workflow on the downloaded files

Need transcription or lyrics/voice extraction:

../audio-transcription/SKILL.md

../video-transcription/SKILL.md

Need subtitle files:
```
../subtitle-packager/SKILL.md
```

需要视频级分析：对下载的文件运行专门的视觉分析工作流

需要转录或歌词/语音提取：使用

../audio-transcription/SKILL.md

或

../video-transcription/SKILL.md

需要字幕文件：使用
```
../subtitle-packager/SKILL.md
```

Rights Posture

版权说明

Treat downloaded TikTok music as research/reference material unless the user confirms rights or platform-licensed use. Do not present extracted audio as cleared for commercial reuse.

除非用户确认拥有版权或平台授权使用，否则请将下载的TikTok音乐视为研究/参考素材。不得将提取的音频展示为可用于商业复用的内容。

Release-Shell Execution Contract

发布Shell执行约定

keep download manifests, reports, extracted videos, and extracted audio under
```
<work-folder>/.postplus/tiktok-music-archive-downloader/
```
keep only final user-facing archive summaries or selected exports outside
```
.postplus/
```
start with a bounded first pass on a very small manifest before broader archive pulls
this skill currently depends on explicit host-installed local tools:
- ```
python3
```
  with
```
yt_dlp
```
- ```
ffmpeg
```
if
```
python3
```
is missing, proactively install
```
python3
```
with the host package manager already present on the machine before continuing

yt_dlp

is missing, proactively run

python3 -m pip install --user yt-dlp

if
```
ffmpeg
```
is missing, proactively install
```
ffmpeg
```
with the host package manager already present on the machine before continuing

rerun direct checks such as

python3 --version

python3 -c "import yt_dlp"

, and

ffmpeg -version

after installation

if installation or verification fails, stop immediately instead of switching to ad hoc shell glue

将下载清单、报告、提取的视频和音频保存在
```
<work-folder>/.postplus/tiktok-music-archive-downloader/
```
目录下
仅将最终面向用户的档案摘要或选定导出内容保存在
```
.postplus/
```
目录外
在进行更广泛的档案拉取前，先对一个非常小的清单进行有限的首次尝试
此技能当前依赖于明确安装在本地的工具：
- 安装了
```
yt_dlp
```
  的
```
python3
```
- ```
ffmpeg
```
如果缺少
```
python3
```
，请主动使用机器上已有的主机包管理器安装
```
python3
```
，然后再继续

如果缺少

yt_dlp

，请主动运行

python3 -m pip install --user yt-dlp

如果缺少
```
ffmpeg
```
，请主动使用机器上已有的主机包管理器安装
```
ffmpeg
```
，然后再继续

安装完成后，重新运行直接检查，如

python3 --version

、

python3 -c "import yt_dlp"

和

ffmpeg -version

如果安装或验证失败，请立即停止，不要改用临时的shell脚本