Douyin Upload Skill

intent

publish local videos to douyin (china mainland) with deterministic cli automation. use this when you need to authorize douyin accounts, upload local video files, auto-generate titles and descriptions from video audio, confirm captions in chat, and push to douyin's official api. fallback to offline outbox export if publish permissions are unavailable.

inputs

environment variables (required):

• DOUYIN_CLIENT_KEY: oauth app client id from douyin open platform
• DOUYIN_CLIENT_SECRET: oauth app client secret
• DOUYIN_REDIRECT_URI: oauth callback url (must match douyin app settings exactly)

environment variables (optional):

• DOUYIN_SCOPE: oauth scope string (defaults to video.create)
• DOUYIN_TOKEN_ENC_KEY: encryption key for stored token (auto-generated if missing)
• DOUYIN_ASR_MODE: speech-to-text backend, one of api, whisper-gpu, whisper-cpu (defaults to whisper-cpu)
• DOUYIN_ASR_API_URL: remote asr endpoint url (only if mode is api)
• DOUYIN_ASR_API_MODEL: asr model name on remote (e.g. whisper-large)
• DOUYIN_ASR_API_KEY: api key for remote asr service
• DOUYIN_WHISPER_BIN: local whisper binary path (only if mode is whisper-gpu or whisper-cpu)
• DOUYIN_WHISPER_MODEL_PATH: local whisper model directory
• DOUYIN_FFMPEG_BIN: ffmpeg binary path (defaults to system ffmpeg)
• DOUYIN_FFPROBE_BIN: ffprobe binary path (defaults to system ffprobe)

external connections:

• douyin open platform oauth endpoint: https://open.douyin.com/platform/oauth/connect (requires valid app credentials)
• douyin video.create api: requires valid oauth token with video.create scope and active upload quota

local file inputs:

• video file path (linux or windows format, e.g. /home/user/video.mp4 or E:\\videos\\demo.mp4)
• must be a valid video container (mp4, mov, webm, etc.) with at least 2 seconds duration

procedure

1. validate environment and dependencies

   • input: system path, env vars
   • run: node <skill_root>/scripts/douyin.js doctor
   • output: json object with keys ok (boolean), missingVars (array), missingBinaries (array), installHints (object)
   • action: if ok is false, stop and display install hints. if ffmpeg/ffprobe are missing, asr will fail later. if whisper binary is missing and mode is whisper-*, asr will fail.

2. authorize douyin oauth account

   • input: DOUYIN_CLIENT_KEY, DOUYIN_CLIENT_SECRET, DOUYIN_REDIRECT_URI from env
   • run: node <skill_root>/scripts/douyin.js auth
   • output: json object with ok (boolean), authUrl (string), token (object with access_token, expires_in)
   • action: open auth url in browser, user signs in, copy callback url or auth code, paste into terminal prompt. token is encrypted and stored in ~/.douyin/token.enc. if oauth fails (invalid creds, network timeout, or user denies), retry auth command. token expires in typically 2 hours; refresh token is not stored, so re-auth is required.

3. extract video metadata and transcript

   • input: video file path (local filesystem)
   • run: node <skill_root>/scripts/douyin.js prepare --video "<path>"
   • output: json object with ok (boolean), command ("prepare"), metadata (object with duration, resolution, fps, filesize), transcript (object with text (string), segments (array)), asrError (optional string if asr failed)
   • action: if asrError is present, log warning but continue to step 4 with empty transcript. if ok is false, stop and display error. accept both linux and windows paths; script normalizes internally.

4. generate three caption candidates from transcript

   • input: transcript.text from step 3
   • in chat or terminal, create 3 caption variants. each caption must have this structure:
     • line 1: attention-grabbing title hook (under 30 chars)
     • lines 2-3: concise description of video content (2-3 sentences, 100-200 chars total)
     • final line: 2-5 hashtags relevant to video topic (space-separated, e.g. #vlog #travel #china)
   • total length for each candidate: max 1000 chars
   • output: three candidate captions as strings

5. confirm final caption with user

   • input: three caption candidates from step 4
   • action: display all three options and ask user to select one or provide custom text. if custom text provided, validate length (max 1000 chars). if user does not confirm, return to step 4.
   • output: one final caption string

6. publish video to douyin

   • input: video file path, final caption text, encrypted token from step 2
   • run: node <skill_root>/scripts/douyin.js publish --video "<path>" --text "<caption>" --private-status 0 --auto-confirm false
   • output: json object with ok (boolean), command ("publish"), mode (string, either official or fallback), videoId (string if mode is official), outboxPath (string if mode is fallback)
   • action: if mode is official, video has been uploaded to douyin api and assigned a videoId. if mode is fallback, api returned a permission-like error (e.g. quota exceeded, ip restricted, invalid scope); fallback files have been written to outbox directory for manual upload later. if ok is false, display error and do not attempt retry in this skill.

decision points

• if asr fails in step 3: continue to step 4 with empty transcript. user can still write captions manually. do not block publish flow.
• if user declines or edits caption in step 5: loop back to step 4 and regenerate candidates if needed, or accept custom text. do not auto-confirm unless DOUYIN_AUTO_CONFIRM=true is set in env.
• if oauth token is expired: publish command will return error token_expired or similar. re-run auth command to refresh. do not store refresh tokens; they are not supported by douyin openapi.
• if douyin api returns permission error in step 6: check mode in output. if fallback, export files are ready. if ok is false, user lacks quota or scope. escalate to manual douyin studio upload.
• if video file is invalid or corrupt: prepare command will fail in step 3 with ok: false. do not proceed to publish. ask user to verify file integrity with ffprobe before retry.
• if asr api is unreachable (mode is api): prepare will return asrError but continue. if critical, user can set DOUYIN_ASR_MODE=whisper-cpu and retry step 3.
• if network timeout or rate limit hit during oauth or publish: scripts return ok: false with error field. wait 30 seconds and retry. if rate limit persists, douyin may be restricting your ip or quota; check douyin console.

output contract

all commands output valid json to stdout. parse results by checking:

• ok (boolean): true if command succeeded, false if error occurred
• command (string): name of command run (doctor, auth, prepare, publish)
• mode (string, publish only): official if api accepted upload, fallback if permission error triggered export
• videoId (string, publish with mode=official only): unique douyin video id for uploaded content
• outboxPath (string, publish with mode=fallback only): directory path containing exported caption and metadata json
• asrError (string, prepare only): error message if speech-to-text failed; presence does not block output
• token (object, auth only): {access_token, expires_in, refresh_token (may be null)}
• metadata (object, prepare only): {duration (seconds), resolution (string, e.g. "1920x1080"), fps (number), filesize (bytes)}
• transcript (object, prepare only): {text (string), segments (array of {start, end, text})}
• error (string, any command): human-readable error message if ok is false

file locations:

• encrypted token: ~/.douyin/token.enc
• fallback outbox: ~/.douyin/outbox/<timestamp>/ (contains caption.json, metadata.json)
• config (if saved): ~/.douyin/config.json

outcome signal

• auth success: terminal prints json with ok: true, token.access_token is non-empty, token file is created at ~/.douyin/token.enc
• prepare success: terminal prints json with ok: true, transcript.text contains extracted speech (or is empty if asr failed), metadata fields are populated
• publish success (official mode): terminal prints json with ok: true, mode: "official", videoId is a non-empty string. video appears in douyin creator dashboard within 1-5 minutes (pending content review).
• publish success (fallback mode): terminal prints json with ok: true, mode: "fallback", outboxPath points to a directory with json files ready for manual upload
• any command failure: terminal prints json with ok: false, error field explains reason (e.g. "token_expired", "video_too_short", "invalid_credentials"). no files are written or modified.