cloud-uploader

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloud Uploader Skill

Upload promo videos and other album content to cloud storage (Cloudflare R2 or AWS S3).

将宣传视频及其他专辑内容上传至云存储（Cloudflare R2或AWS S3）。

Purpose

用途

After generating promo videos with

/bitwize-music:promo-director

, upload them to cloud storage for:

Hosting on websites
Sharing via direct links
CDN distribution
Backup and archival

使用

/bitwize-music:promo-director

生成宣传视频后，将其上传至云存储以用于：

网站托管
通过直接链接分享
CDN分发
备份与归档

When to Use

使用场景

After promo videos generated, user wants to upload to cloud
User says "upload promos to R2" or "upload to S3"
User says "upload promo videos for [album]"
Manual invocation only (not automatic)

生成宣传视频后，用户希望上传至云端
用户说“将宣传内容上传至R2”或“上传至S3”
用户说“为[专辑]上传宣传视频”
仅支持手动调用（非自动触发）

Position in Workflow

在工作流中的位置

Generate → Master → Promo Videos → **[Cloud Upload]** → Release

Optional step after promo-director, before release-director.

生成 → 母带制作 → 宣传视频 → **[云上传]** → 发布

是promo-director之后、release-director之前的可选步骤。

Prerequisites

前提条件

Cloud Configuration

云配置

Cloud credentials must be configured in

~/.bitwize-music/config.yaml

yaml

cloud:
  enabled: true
  provider: "r2"  # or "s3"

  # For Cloudflare R2
  r2:
    account_id: "your-account-id"
    access_key_id: "your-access-key"
    secret_access_key: "your-secret-key"
    bucket: "promo-videos"

  # For AWS S3
  s3:
    region: "us-west-2"
    access_key_id: "your-access-key"
    secret_access_key: "your-secret-key"
    bucket: "promo-videos"

See

${CLAUDE_PLUGIN_ROOT}/reference/cloud/setup-guide.md

for detailed setup instructions.

必须在

~/.bitwize-music/config.yaml

中配置云凭证：

yaml

cloud:
  enabled: true
  provider: "r2"  # or "s3"

  # For Cloudflare R2
  r2:
    account_id: "your-account-id"
    access_key_id: "your-access-key"
    secret_access_key: "your-secret-key"
    bucket: "promo-videos"

  # For AWS S3
  s3:
    region: "us-west-2"
    access_key_id: "your-access-key"
    secret_access_key: "your-secret-key"
    bucket: "promo-videos"

详细设置说明请参见

${CLAUDE_PLUGIN_ROOT}/reference/cloud/setup-guide.md

。

Required Files

所需文件

Promo videos generated (run
```
/bitwize-music:promo-director
```
first)

Located at:

{audio_root}/artists/{artist}/albums/{genre}/{album}/promo_videos/

Album sampler at:

{audio_root}/artists/{artist}/albums/{genre}/{album}/album_sampler.mp4

已生成宣传视频（需先运行
```
/bitwize-music:promo-director
```
）

存储路径：

{audio_root}/artists/{artist}/albums/{genre}/{album}/promo_videos/

专辑 sampler 路径：

{audio_root}/artists/{artist}/albums/{genre}/{album}/album_sampler.mp4

Python Dependencies

Python依赖

bash

undefined

bash

undefined

If using the shared venv (recommended)

~/.bitwize-music/venv/bin/pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt

Or install separately

pip install boto3


The upload script uses `~/.bitwize-music/venv` if available, otherwise falls back to system Python.

pip install boto3


上传脚本会优先使用`~/.bitwize-music/venv`（若存在），否则回退到系统Python。

Workflow

工作流

1. Verify Prerequisites

1. 验证前提条件

Check config:

bash

cat ~/.bitwize-music/config.yaml | grep -A 20 "cloud:"

Verify:

```
cloud.enabled: true
```
Provider credentials configured (r2 or s3)
Bucket name set

Check promo videos exist:

bash

ls {audio_root}/artists/{artist}/albums/{genre}/{album}/promo_videos/
ls {audio_root}/artists/{artist}/albums/{genre}/{album}/album_sampler.mp4

If missing:

Error: Promo videos not found.

Generate with: /bitwize-music:promo-director {album}

检查配置：

bash

cat ~/.bitwize-music/config.yaml | grep -A 20 "cloud:"

需验证：

```
cloud.enabled: true
```
已配置服务商凭证（r2或s3）
已设置存储桶名称

检查宣传视频是否存在：

bash

ls {audio_root}/artists/{artist}/albums/{genre}/{album}/promo_videos/
ls {audio_root}/artists/{artist}/albums/{genre}/{album}/album_sampler.mp4

若缺失：

错误：未找到宣传视频。

请先生成：/bitwize-music:promo-director {album}

2. Get Python Command

2. 获取Python命令

Call
get_python_command()
first to get the venv Python path and plugin root. Use these for all bash invocations below.

PYTHON="{python from get_python_command}"
PLUGIN_DIR="{plugin_root from get_python_command}"

**先调用

get_python_command()

**获取虚拟环境Python路径和插件根目录。以下所有bash调用均需使用这些变量。

PYTHON="{python from get_python_command}"
PLUGIN_DIR="{plugin_root from get_python_command}"

3. Preview Upload (Dry Run)

3. 预览上传（试运行）

Preview first:

bash

$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album} --dry-run

Output shows:

Provider and bucket
Files to upload
S3 keys (paths in bucket)
File sizes

先进行预览：

bash

$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album} --dry-run

输出内容包括：

服务商与存储桶
待上传文件
S3键（存储桶中的路径）
文件大小

4. Upload Files

4. 上传文件

Upload all (promos + sampler):

bash

$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album}

Upload only track promos:

bash

$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album} --type promos

Upload only album sampler:

bash

$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album} --type sampler

Upload with public access:

bash

$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album} --public

上传全部内容（宣传视频+sampler）：

bash

$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album}

仅上传单轨宣传视频：

bash

$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album} --type promos

仅上传专辑sampler：

bash

$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album} --type sampler

上传并设置公共访问权限：

bash

$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album} --public

5. Verify Upload

5. 验证上传

For R2:

Check Cloudflare dashboard → R2 → Your bucket
Files should appear under
```
{artist}/{album}/
```

For S3:

Check AWS Console → S3 → Your bucket

Or use AWS CLI:

aws s3 ls s3://{bucket}/{artist}/{album}/

对于R2：

查看Cloudflare控制台 → R2 → 你的存储桶
文件应显示在
```
{artist}/{album}/
```
路径下

对于S3：

查看AWS控制台 → S3 → 你的存储桶

或使用AWS CLI：

aws s3 ls s3://{bucket}/{artist}/{album}/

5. Report Results

5. 报告结果

undefined

undefined

Cloud Upload Complete

云上传完成

Provider: R2 (or S3) Bucket: {bucket} Album: {album}

Uploaded Files:

{artist}/{album}/promos/01-track_promo.mp4
{artist}/{album}/promos/02-track_promo.mp4
...
{artist}/{album}/promos/album_sampler.mp4

Total: 11 files, 125.4 MB

Next Steps:

Verify files in cloud dashboard
If public: Test URLs work
Continue to release: /bitwize-music:release-director {album}

undefined

服务商： R2（或S3） 存储桶： {bucket} 专辑： {album}

已上传文件：

{artist}/{album}/promos/01-track_promo.mp4
{artist}/{album}/promos/02-track_promo.mp4
...
{artist}/{album}/promos/album_sampler.mp4

总计： 11个文件，125.4 MB

下一步：

在云控制台中验证文件
若为公共访问：测试URL是否可用
进入发布流程：/bitwize-music:release-director {album}

undefined

Upload Path Structure

上传路径结构

IMPORTANT: Cloud paths are FLAT - no genre folder.

The cloud path structure is different from the local content structure:

Location	Path Structure
Local content	`{content_root}/artists/{artist}/albums/{genre}/{album}/`
Local audio	`{audio_root}/artists/{artist}/albums/{genre}/{album}/`
Cloud	`{artist}/{album}/` (no genre!)

Files are organized in the bucket as:

{bucket}/
└── {artist}/
    └── {album}/
        └── promos/
            ├── 01-track_promo.mp4
            ├── 02-track_promo.mp4
            ├── ...
            └── album_sampler.mp4

Example for album "my-album" by "bitwize" in rock genre:

Local:

~/music/artists/bitwize/albums/rock/my-album/

Cloud:

bitwize/my-album/promos/

(NOT

bitwize/albums/rock/my-album/

)

重要提示：云端路径为扁平结构 - 无流派文件夹。

云端路径结构与本地内容结构不同：

位置	路径结构
本地内容	`{content_root}/artists/{artist}/albums/{genre}/{album}/`
本地音频	`{audio_root}/artists/{artist}/albums/{genre}/{album}/`
云端	`{artist}/{album}/` （无流派文件夹！）

文件在存储桶中的组织方式：

{bucket}/
└── {artist}/
    └── {album}/
        └── promos/
            ├── 01-track_promo.mp4
            ├── 02-track_promo.mp4
            ├── ...
            └── album_sampler.mp4

示例：摇滚流派中bitwize艺人的专辑"my-album"

本地路径：

~/music/artists/bitwize/albums/rock/my-album/

云端路径：

bitwize/my-album/promos/

（而非

bitwize/albums/rock/my-album/

）

Command Options

命令选项

Option	Description
`--type promos`	Upload only track promo videos
`--type sampler`	Upload only album sampler
`--type all`	Upload both (default)
`--dry-run`	Preview without uploading
`--public`	Set files as public-read
`--audio-root PATH`	Override audio_root from config

选项	描述
`--type promos`	仅上传单轨宣传视频
`--type sampler`	仅上传专辑sampler
`--type all`	上传全部内容（默认）
`--dry-run`	预览上传内容，不实际执行上传
`--public`	将文件设置为公共可读
`--audio-root PATH`	覆盖配置中的audio_root路径

Invocation Examples

调用示例

Basic upload:

/bitwize-music:cloud-uploader my-album

Preview only:

/bitwize-music:cloud-uploader my-album --dry-run

Upload promos only:

/bitwize-music:cloud-uploader my-album --type promos

Upload with public access:

/bitwize-music:cloud-uploader my-album --public

基础上传：

/bitwize-music:cloud-uploader my-album

仅预览：

/bitwize-music:cloud-uploader my-album --dry-run

仅上传宣传视频：

/bitwize-music:cloud-uploader my-album --type promos

上传并设置公共访问：

/bitwize-music:cloud-uploader my-album --public

Error Handling

错误处理

"Cloud uploads not enabled"

Add
```
cloud.enabled: true
```
to config

See

${CLAUDE_PLUGIN_ROOT}/reference/cloud/setup-guide.md

"Credentials not configured"

Add credentials to config file
For R2: account_id, access_key_id, secret_access_key
For S3: access_key_id, secret_access_key

"Album not found"

Check album exists in

{audio_root}/artists/{artist}/albums/{genre}/{album}/

Verify artist name in config matches

"No files found to upload"

Generate promo videos first:
```
/bitwize-music:promo-director {album}
```

"Access Denied"

Check credentials are correct
For R2: Verify API token has write permissions
For S3: Verify IAM policy allows s3:PutObject

"Bucket not found"

Create bucket first in cloud dashboard
Verify bucket name in config

"云上传未启用"

在配置中添加
```
cloud.enabled: true
```

参见

${CLAUDE_PLUGIN_ROOT}/reference/cloud/setup-guide.md

"未配置凭证"

在配置文件中添加凭证
对于R2：account_id、access_key_id、secret_access_key
对于S3：access_key_id、secret_access_key

"未找到专辑"

检查专辑是否存在于

{audio_root}/artists/{artist}/albums/{genre}/{album}/

路径下

验证配置中的艺人名称是否匹配

"未找到待上传文件"

先生成宣传视频：
```
/bitwize-music:promo-director {album}
```

"访问被拒绝"

检查凭证是否正确
对于R2：验证API令牌是否有写入权限
对于S3：验证IAM策略是否允许s3:PutObject操作

"未找到存储桶"

先在云控制台中创建存储桶
验证配置中的存储桶名称是否正确

Security Notes

安全注意事项

Credentials stored in config file (ensure proper file permissions)
Config file should be gitignored in user's content repo
Default: Files uploaded as private (not public)
Use
```
--public
```
flag only for files intended for public access
Consider using environment variables for CI/CD (future enhancement)

凭证存储在配置文件中（确保设置合适的文件权限）
配置文件应在用户的内容仓库中设置为git忽略
默认：文件上传为私有（非公共）
仅对需要公共访问的文件使用
```
--public
```
标志
考虑在CI/CD中使用环境变量（未来增强功能）

Integration with Other Skills

与其他技能的集成

Handoff FROM

来自其他技能的交接

promo-director:

After promo generation:

Promo videos generated successfully.

**Optional:** Upload to cloud storage: /bitwize-music:cloud-uploader {album}

promo-director：

宣传视频生成完成后：

宣传视频生成成功。

**可选操作：** 上传至云存储：/bitwize-music:cloud-uploader {album}

Handoff TO

交接至其他技能

release-director:

After cloud upload:

Cloud upload complete.

Ready for release workflow: /bitwize-music:release-director {album}

release-director：

云上传完成后：

云上传完成。

准备进入发布工作流：/bitwize-music:release-director {album}

Supported Providers

支持的服务商

Cloudflare R2

S3-compatible API
No egress fees
Global CDN integration
Good for high-traffic content

兼容S3的API
无出口费用
全球CDN集成
适合高流量内容

AWS S3

Industry standard
Fine-grained IAM permissions
CloudFront CDN available
Good for AWS ecosystem integration

行业标准
细粒度IAM权限
可集成CloudFront CDN
适合AWS生态系统集成

Future Enhancements

未来增强功能

Environment variable credentials (for CI/CD)
Multiple bucket support
Automatic CDN invalidation
Progress bar for large uploads
Resume failed uploads
Bucket creation if missing
Additional providers (Backblaze B2, DigitalOcean Spaces)

支持环境变量存储凭证（用于CI/CD）
多存储桶支持
自动CDN失效
大文件上传进度条
断点续传
自动创建缺失的存储桶
支持更多服务商（Backblaze B2、DigitalOcean Spaces）

Model Recommendation

模型推荐

Sonnet 4.5 - This skill runs scripts and coordinates workflow. No creative output from LLM.

Sonnet 4.5 - 本技能用于运行脚本和协调工作流，无需LLM生成创意内容。

Version History

版本历史

v0.14.0 - Initial implementation
- R2 and S3 support via boto3
- Dry-run mode
- Public/private upload options
- Path organization by artist/album

v0.14.0 - 初始实现
- 通过boto3支持R2和S3
- 试运行模式
- 公共/私有上传选项
- 按艺人/专辑组织路径

cloud-uploader

Original

Translation

Cloud Uploader Skill

Cloud Uploader Skill

Purpose

用途

When to Use

使用场景

Position in Workflow

在工作流中的位置

Prerequisites

前提条件

Cloud Configuration

云配置

Required Files

所需文件

Python Dependencies

Python依赖

If using the shared venv (recommended)

If using the shared venv (recommended)

Or install separately

Or install separately

Workflow

工作流

1. Verify Prerequisites

1. 验证前提条件

2. Get Python Command

2. 获取Python命令

3. Preview Upload (Dry Run)

3. 预览上传（试运行）

4. Upload Files

4. 上传文件

5. Verify Upload

5. 验证上传

5. Report Results

5. 报告结果

Cloud Upload Complete

云上传完成

Upload Path Structure

上传路径结构

Command Options

命令选项

Invocation Examples

调用示例

Error Handling

错误处理

Security Notes

安全注意事项

Integration with Other Skills

与其他技能的集成

Handoff FROM

来自其他技能的交接

Handoff TO

交接至其他技能

Supported Providers

支持的服务商

Cloudflare R2

Cloudflare R2

AWS S3

AWS S3

Future Enhancements

未来增强功能

Related Documentation

相关文档

Model Recommendation

模型推荐

Version History

版本历史