ytstudio-cli 0.4.2__tar.gz → 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. ytstudio_cli-0.5.0/.github/dependabot.yml +21 -0
  2. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/.github/workflows/docs.yml +4 -4
  3. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/.github/workflows/release.yml +5 -5
  4. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/.github/workflows/test.yml +5 -5
  5. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/.pre-commit-config.yaml +2 -2
  6. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/PKG-INFO +5 -2
  7. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/README.md +2 -0
  8. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/docs/api-quota.md +8 -0
  9. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/docs/index.md +4 -0
  10. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/docs/profiles.md +26 -1
  11. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/docs/videos.md +71 -0
  12. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/mkdocs.yml +1 -1
  13. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/pyproject.toml +3 -1
  14. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/skills/ytstudio/SKILL.md +105 -0
  15. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/skills/ytstudio/references/reference.md +241 -133
  16. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/commands/playlists.py +11 -2
  17. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/commands/profile.py +83 -0
  18. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/commands/videos.py +176 -12
  19. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/config.py +17 -0
  20. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/conftest.py +37 -0
  21. ytstudio_cli-0.5.0/tests/test_captions.py +157 -0
  22. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_playlists.py +46 -0
  23. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_profile.py +95 -0
  24. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_videos.py +107 -0
  25. ytstudio_cli-0.5.0/uv.lock +1552 -0
  26. ytstudio_cli-0.4.2/uv.lock +0 -1284
  27. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/.editorconfig +0 -0
  28. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/.github/workflows/ci.yml +0 -0
  29. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/.gitignore +0 -0
  30. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/.python-version +0 -0
  31. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/LICENSE +0 -0
  32. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/ascii.png +0 -0
  33. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/docs/analytics.md +0 -0
  34. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/docs/comments.md +0 -0
  35. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/docs/installation.md +0 -0
  36. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/docs/livestreams.md +0 -0
  37. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/docs/playlists.md +0 -0
  38. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/docs/setup.md +0 -0
  39. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/docs/stylesheets/extra.css +0 -0
  40. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/scripts/build_docs_reference.py +0 -0
  41. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/scripts/build_skill_reference.py +0 -0
  42. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/skills/ytstudio/assets/upload-sidecar.example.yaml +0 -0
  43. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/__init__.py +0 -0
  44. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/api.py +0 -0
  45. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/commands/__init__.py +0 -0
  46. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/commands/analytics.py +0 -0
  47. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/commands/comments.py +0 -0
  48. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/commands/livestreams.py +0 -0
  49. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/commands/upload.py +0 -0
  50. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/main.py +0 -0
  51. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/registry.py +0 -0
  52. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/services.py +0 -0
  53. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/ui.py +0 -0
  54. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/upload_pipeline.py +0 -0
  55. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/src/ytstudio/version.py +0 -0
  56. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/__init__.py +0 -0
  57. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_analytics.py +0 -0
  58. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_api.py +0 -0
  59. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_comments.py +0 -0
  60. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_config.py +0 -0
  61. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_livestreams.py +0 -0
  62. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_main.py +0 -0
  63. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_registry.py +0 -0
  64. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_skill_reference.py +0 -0
  65. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_upload_command.py +0 -0
  66. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_upload_pipeline.py +0 -0
  67. {ytstudio_cli-0.4.2 → ytstudio_cli-0.5.0}/tests/test_version.py +0 -0
@@ -0,0 +1,21 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: uv
4
+ directory: /
5
+ schedule:
6
+ interval: weekly
7
+ groups:
8
+ python-minor-patch:
9
+ update-types: [minor, patch]
10
+ commit-message:
11
+ prefix: chore
12
+
13
+ - package-ecosystem: github-actions
14
+ directory: /
15
+ schedule:
16
+ interval: weekly
17
+ groups:
18
+ actions-minor-patch:
19
+ update-types: [minor, patch]
20
+ commit-message:
21
+ prefix: chore
@@ -30,12 +30,12 @@ jobs:
30
30
  runs-on: ubuntu-latest
31
31
  steps:
32
32
  - name: Checkout
33
- uses: actions/checkout@v6
33
+ uses: actions/checkout@v7.0.1
34
34
  with:
35
35
  fetch-depth: 0
36
36
 
37
37
  - name: Install uv
38
- uses: astral-sh/setup-uv@v7
38
+ uses: astral-sh/setup-uv@v10.3.3
39
39
 
40
40
  - name: Set up Python
41
41
  run: uv python install 3.12
@@ -48,7 +48,7 @@ jobs:
48
48
 
49
49
  - name: Upload Pages artifact
50
50
  if: github.event_name != 'pull_request'
51
- uses: actions/upload-pages-artifact@v5
51
+ uses: actions/upload-pages-artifact@v5.0.0
52
52
  with:
53
53
  path: site
54
54
 
@@ -62,4 +62,4 @@ jobs:
62
62
  steps:
63
63
  - name: Deploy to GitHub Pages
64
64
  id: deployment
65
- uses: actions/deploy-pages@v5
65
+ uses: actions/deploy-pages@v5.0.1
@@ -21,10 +21,10 @@ jobs:
21
21
  runs-on: ubuntu-latest
22
22
 
23
23
  steps:
24
- - uses: actions/checkout@v6
24
+ - uses: actions/checkout@v7.0.1
25
25
 
26
26
  - name: Install uv
27
- uses: astral-sh/setup-uv@v7
27
+ uses: astral-sh/setup-uv@v10.3.3
28
28
  with:
29
29
  enable-cache: true
30
30
 
@@ -72,7 +72,7 @@ jobs:
72
72
  /tmp/ytstudio-smoke/bin/ytstudio videos --help
73
73
 
74
74
  - name: Upload dist artifacts
75
- uses: actions/upload-artifact@v4
75
+ uses: actions/upload-artifact@v7.0.2
76
76
  with:
77
77
  name: dist
78
78
  path: dist/
@@ -87,10 +87,10 @@ jobs:
87
87
 
88
88
  steps:
89
89
  - name: Download dist artifacts
90
- uses: actions/download-artifact@v4
90
+ uses: actions/download-artifact@v8.0.2
91
91
  with:
92
92
  name: dist
93
93
  path: dist/
94
94
 
95
95
  - name: Publish to PyPI
96
- uses: pypa/gh-action-pypi-publish@release/v1
96
+ uses: pypa/gh-action-pypi-publish@v1.14.3
@@ -19,13 +19,13 @@ jobs:
19
19
  runs-on: ubuntu-latest
20
20
  strategy:
21
21
  matrix:
22
- python-version: ["3.12", "3.13"]
22
+ python-version: ["3.12", "3.13", "3.14"]
23
23
 
24
24
  steps:
25
- - uses: actions/checkout@v6
25
+ - uses: actions/checkout@v7.0.1
26
26
 
27
27
  - name: Install uv
28
- uses: astral-sh/setup-uv@v7
28
+ uses: astral-sh/setup-uv@v10.3.3
29
29
  with:
30
30
  enable-cache: true
31
31
 
@@ -60,7 +60,7 @@ jobs:
60
60
 
61
61
  - name: Upload coverage artifacts
62
62
  if: inputs.coverage && matrix.python-version == '3.12'
63
- uses: actions/upload-artifact@v4
63
+ uses: actions/upload-artifact@v7.0.2
64
64
  with:
65
65
  name: coverage-report
66
66
  path: |
@@ -69,7 +69,7 @@ jobs:
69
69
 
70
70
  - name: Upload coverage to Codecov
71
71
  if: inputs.coverage && matrix.python-version == '3.12'
72
- uses: codecov/codecov-action@v5
72
+ uses: codecov/codecov-action@v7.1.1
73
73
  with:
74
74
  files: coverage.xml
75
75
  fail_ci_if_error: false
@@ -10,8 +10,8 @@ repos:
10
10
  - id: check-merge-conflict
11
11
 
12
12
  - repo: https://github.com/astral-sh/ruff-pre-commit
13
- rev: v0.15.0
13
+ rev: v0.17.6
14
14
  hooks:
15
- - id: ruff
15
+ - id: ruff-check
16
16
  args: [--fix]
17
17
  - id: ruff-format
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: ytstudio-cli
3
- Version: 0.4.2
3
+ Version: 0.5.0
4
4
  Summary: Manage and analyze your YouTube channel from the terminal. Designed for humans and AI agents.
5
5
  Project-URL: Homepage, https://github.com/jdwit/ytstudio-cli
6
6
  Project-URL: Repository, https://github.com/jdwit/ytstudio-cli
@@ -15,6 +15,7 @@ Classifier: License :: OSI Approved :: MIT License
15
15
  Classifier: Programming Language :: Python :: 3
16
16
  Classifier: Programming Language :: Python :: 3.12
17
17
  Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
18
19
  Requires-Python: >=3.12
19
20
  Requires-Dist: google-api-python-client>=2.0.0
20
21
  Requires-Dist: google-auth-oauthlib>=1.0.0
@@ -64,6 +65,8 @@ command line.
64
65
  - Comments moderation: list, reply, approve, reject, and ban from the CLI.
65
66
  - Channel analytics queries via the YouTube Analytics API.
66
67
  - Playlists: bulk-add by search and reorder by views with one command.
68
+ - Agentic authoring: use your LLM to write descriptions and edit metadata, based on the actual
69
+ video transcript and guided by a per-channel tone of voice.
67
70
 
68
71
  ## Documentation
69
72
 
@@ -36,6 +36,8 @@ command line.
36
36
  - Comments moderation: list, reply, approve, reject, and ban from the CLI.
37
37
  - Channel analytics queries via the YouTube Analytics API.
38
38
  - Playlists: bulk-add by search and reorder by views with one command.
39
+ - Agentic authoring: use your LLM to write descriptions and edit metadata, based on the actual
40
+ video transcript and guided by a per-channel tone of voice.
39
41
 
40
42
  ## Documentation
41
43
 
@@ -25,6 +25,8 @@ not eat into the table below.
25
25
  | `liveBroadcasts.list` | 1 unit |
26
26
  | `playlists.list` | 1 unit |
27
27
  | `playlistItems.list` | 1 unit |
28
+ | `captions.list` (`videos captions`) | 50 units |
29
+ | `captions.download` (`videos transcript`) | 200 units |
28
30
  | `search.list` | 100 units |
29
31
  | `videos.update` | 50 units |
30
32
  | `comments.setModerationStatus` | 50 units |
@@ -41,6 +43,12 @@ At ~1600 units per upload, the default 10 000-unit daily budget covers about
41
43
  six new videos per day. Use `ytstudio videos upload --max N` to cap a run
42
44
  and avoid burning the budget you need for the rest of the day.
43
45
 
46
+ Captions are the other pricey read: `videos transcript` first lists the tracks
47
+ (`captions.list`, 50 units) and then downloads the chosen one
48
+ (`captions.download`, 200 units), so a single transcript spends about 250 units.
49
+ Author metadata per video rather than pulling transcripts across a whole
50
+ channel.
51
+
44
52
  ## Increasing the quota
45
53
 
46
54
  In the Google Cloud Console, go to **IAM & Admin** :material-arrow-right:
@@ -28,6 +28,10 @@ and plug your channel into AI agent workflows.
28
28
  - **Batch upload** from a directory of YAML
29
29
  sidecars with resumable, quota-aware behaviour. See
30
30
  [Upload a batch from sidecars](videos.md#upload-a-batch-from-sidecars).
31
+ - **Inputs for transcript-grounded, on-brand authoring**:
32
+ read caption tracks, pull a clean transcript, and store a per-channel brand
33
+ voice, so an agent can write titles and descriptions and apply them via
34
+ `videos update`. See [Authoring metadata](videos.md#authoring-metadata).
31
35
  - **Scripted analytics** with table or JSON output.
32
36
  See [Analytics](analytics.md).
33
37
  - **Live broadcast control** for the full lifecycle:
@@ -24,6 +24,30 @@ state.
24
24
  YTSTUDIO_PROFILE=work ytstudio videos list
25
25
  ```
26
26
 
27
+ ## Brand voice
28
+
29
+ Each profile can carry a **brand voice**: a markdown file describing the house
30
+ style an agent should follow when authoring video metadata. It is stored next
31
+ to the profile's credentials and fed verbatim into an agent's context by
32
+ [metadata authoring](videos.md#authoring-metadata).
33
+
34
+ ```bash
35
+ ytstudio profile brand show # print the active profile's brand voice
36
+ ytstudio profile brand edit # create/open brand.md in $EDITOR
37
+ ytstudio profile brand set --file style.md # import a brand file non-interactively
38
+ ytstudio profile brand show --profile work # target a specific profile
39
+ ```
40
+
41
+ `brand edit` seeds a template on first use and opens `$EDITOR`; `brand set`
42
+ imports an existing markdown file. All three accept `--profile/-p` to target a
43
+ profile other than the active one. `brand show` prints the raw markdown to
44
+ stdout so an agent can capture it into a system prompt, and exits non-zero when
45
+ no brand voice is set yet.
46
+
47
+ The file lives at `profiles/<name>/brand.md` and is written owner-only
48
+ (`0600`), the same as credentials, because a brand voice can encode private
49
+ channel strategy.
50
+
27
51
  ## Storage
28
52
 
29
53
  ```
@@ -36,7 +60,8 @@ YTSTUDIO_PROFILE=work ytstudio videos list
36
60
  │ └── meta.json
37
61
  └── work/
38
62
  ├── credentials.json
39
- └── meta.json
63
+ ├── meta.json
64
+ └── brand.md # optional; per-channel brand voice (0600)
40
65
  ```
41
66
 
42
67
  Profile directories are `0700`; credential files are `0600`. State writes go
@@ -59,6 +59,77 @@ Flags:
59
59
  touches 200 videos eats the default daily quota (10 000 units). See
60
60
  [API quota](api-quota.md) before kicking off large jobs.
61
61
 
62
+ ## Captions and transcripts
63
+
64
+ Read a video's caption tracks, or pull one down as clean plain text. This is
65
+ the raw material for [metadata authoring](#authoring-metadata) below and for
66
+ any workflow that needs the spoken content of a video.
67
+
68
+ ```bash
69
+ ytstudio videos captions <video-id> # list tracks (language, kind, draft)
70
+ ytstudio videos captions <video-id> -o json # same, parseable
71
+ ytstudio videos transcript <video-id> # best track as plain text
72
+ ytstudio videos transcript <video-id> --lang nl # a specific language
73
+ ytstudio videos transcript <video-id> -o json # transcript plus track metadata
74
+ ```
75
+
76
+ `captions` lists every track with its `language`, `track_kind` (`standard`
77
+ for human-authored, `ASR` for auto-generated, `forced`), and whether it is a
78
+ draft. `transcript` downloads one track and strips the SRT timing and markup,
79
+ leaving one cue per line.
80
+
81
+ Without `--lang`, `transcript` prefers a `standard` (human) track over `ASR`
82
+ across all languages, which may not be the language you want on a
83
+ multi-language channel. List the tracks first and pass the exact code; if the
84
+ requested language has no track, the command exits with the available codes.
85
+ Auto-generated (ASR) tracks are often restricted by YouTube and may not be
86
+ downloadable; `transcript` then prints a warning and exits non-zero, so fall
87
+ back to `captions` and pick another track.
88
+
89
+ !!! warning "Quota cost"
90
+
91
+ Listing caption tracks costs about 50 units and downloading a transcript
92
+ about 200, both well above ordinary 1-unit reads. Author per video rather
93
+ than scanning a whole channel. See [API quota](api-quota.md).
94
+
95
+ ## Authoring metadata
96
+
97
+ Writing a good title or description is per-video creative work. ytstudio does
98
+ not generate copy for you; it supplies the two inputs you need to write it
99
+ well, and the existing `videos update` path applies the result:
100
+
101
+ - the channel's **brand voice** (`ytstudio profile brand show`) as the source
102
+ of truth for tone and house style; and
103
+ - the video's **transcript** (`ytstudio videos transcript`) as the source of
104
+ truth for what the video actually says.
105
+
106
+ A single-video loop:
107
+
108
+ ```bash
109
+ ytstudio profile brand show # house style / tone
110
+ ytstudio videos captions <id> -o json # pick a language and track kind
111
+ ytstudio videos transcript <id> --lang nl # spoken content
112
+ ytstudio videos show <id> -o json # current title/description/tags
113
+ ytstudio videos update <id> --title "..." --description "..." # dry-run preview
114
+ ytstudio videos update <id> --title "..." --execute # apply
115
+ ```
116
+
117
+ The rules that keep the output honest:
118
+
119
+ - **Brand file for tone, transcript for claims.** Never state anything the
120
+ transcript does not support, and never invent content. If there is no usable
121
+ transcript, tell the user rather than authoring from nothing.
122
+ - **Gate the expensive call.** Run `captions` first and skip `transcript` for
123
+ any video without a usable track; a caption list is about 50 units against
124
+ 200 for a download.
125
+ - **Preview, then execute.** `videos update` is dry-run by default; show the
126
+ user consequential changes before re-running with `--execute`.
127
+
128
+ Set the brand voice once per channel; see [Brand voice](profiles.md#brand-voice).
129
+ The [agent skill](https://github.com/jdwit/ytstudio-cli/tree/main/skills/ytstudio)
130
+ bundled with this repo drives the same loop, including bulk backfill across a
131
+ set of videos.
132
+
62
133
  ## Upload a batch from sidecars
63
134
 
64
135
  `videos upload` takes a video file or a directory, pairs each `.mp4`/`.mov`
@@ -95,7 +95,7 @@ nav:
95
95
  - Guides:
96
96
  - Multi-channel profiles: profiles.md
97
97
  - Live broadcasts: livestreams.md
98
- - Videos (bulk update, upload): videos.md
98
+ - Videos (bulk update, upload, authoring): videos.md
99
99
  - Playlists: playlists.md
100
100
  - Analytics: analytics.md
101
101
  - Comments: comments.md
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "ytstudio-cli"
3
- version = "0.4.2"
3
+ version = "0.5.0"
4
4
  description = "Manage and analyze your YouTube channel from the terminal. Designed for humans and AI agents."
5
5
  readme = "README.md"
6
6
  license = { text = "MIT" }
@@ -17,6 +17,7 @@ classifiers = [
17
17
  "Programming Language :: Python :: 3",
18
18
  "Programming Language :: Python :: 3.12",
19
19
  "Programming Language :: Python :: 3.13",
20
+ "Programming Language :: Python :: 3.14",
20
21
  ]
21
22
 
22
23
  dependencies = [
@@ -99,6 +100,7 @@ ignore = [
99
100
  "E501", # line too long (handled by formatter)
100
101
  "B008", # function call in default argument (typer pattern)
101
102
  "PLR0913", # too many arguments
103
+ "PLR0917", # too many positional arguments (typer pattern)
102
104
  "PLR0912", # too many branches
103
105
  "PLR0915", # too many statements
104
106
  "PLR2004", # magic value comparison
@@ -142,6 +142,109 @@ json` returns a flat object with fields such as `title`, `published_at`,
142
142
  10). Preview the dry-run, confirm the match set is what the user intended, then
143
143
  add `--execute`.
144
144
 
145
+ ### authoring metadata - transcript-grounded, on-brand
146
+
147
+ Writing a good title or description is per-video creative work. The CLI supplies
148
+ the two raw materials an agent needs to do it well; you write the copy, and the
149
+ existing `videos update` path applies it.
150
+
151
+ ```bash
152
+ ytstudio profile brand show # house style / tone (system context)
153
+ ytstudio videos captions <id> -o json # list caption tracks, pick a language/kind
154
+ ytstudio videos transcript <id> --lang nl # spoken content, the source of truth for claims
155
+ ytstudio videos show <id> -o json # current title/description/tags
156
+ ytstudio videos update <id> --title "..." --description "..." --tags a,b,c # dry-run preview
157
+ ytstudio videos update <id> --title "..." --execute # apply
158
+ ```
159
+
160
+ The authoring loop and its rules:
161
+
162
+ - **The brand file is the source of truth for tone; the transcript is the source
163
+ of truth for claims.** Never state anything the transcript does not support,
164
+ and never invent content.
165
+ - Set the brand voice once per channel with `ytstudio profile brand edit` (opens
166
+ `$EDITOR`) or `... brand set --file <path>`; it is stored at
167
+ `profiles/<name>/brand.md` and printed verbatim by `brand show`.
168
+ - **Prefer a `standard` (human) track over `ASR` (auto-generated).** `videos
169
+ captions -o json` returns one object per track with `language`, `track_kind`
170
+ (`standard`/`ASR`/`forced`), and `is_draft`; pick the `standard` track in the
171
+ language you want. `transcript` defaults to clean plain text; `-o json` adds
172
+ the track metadata.
173
+ - **Multi-language channels: pass `--lang` explicitly.** Without `--lang`,
174
+ `transcript` auto-picks (preferring `standard` over `ASR`) across all tracks,
175
+ which may not be the language you mean. Read the `language` codes from
176
+ `videos captions` first, then pass the exact one, e.g. `--lang nl`. If the
177
+ requested language has no track, `transcript` exits with an error listing the
178
+ available codes - re-run with one of those.
179
+ - **When only ASR exists, use it but treat claims with extra care**, since
180
+ auto-generated text is noisier; the brand-vs-transcript rule still holds.
181
+ - If there is no usable transcript (no tracks, or a track exists but is not
182
+ downloadable - common for restricted ASR, where `transcript` prints a yellow
183
+ warning and exits non-zero), fall back to `videos captions` to pick another
184
+ track, and if none is usable **tell the user instead of authoring from
185
+ nothing.**
186
+ - Draft, then **preview with `videos update` (dry-run), show the user when the
187
+ change is consequential, then `--execute`** (see the two-rules-first section).
188
+
189
+ `videos captions` (~50 units) and `videos transcript` (~200 units) cost more
190
+ than ordinary reads, so author per-video rather than scanning a whole channel.
191
+
192
+ **Bound the batch against the 10,000 units/day budget.** Per fully-authored
193
+ video the worst case is ~50 (captions gate) + ~250 (transcript, which itself
194
+ lists then downloads) + ~50 (update) = ~350 units, so roughly 28 videos exhaust
195
+ a fresh daily budget on their own. The captions gate still pays for itself: it
196
+ skips the ~250-unit transcript entirely for videos with no usable track (its
197
+ only redundancy is the cheap list call, paid twice when a track does exist).
198
+ Estimate `candidates x 350` before you start, subtract any quota already spent
199
+ that day, and **warn the user before a run that could blow the budget** rather
200
+ than discovering `quotaExceeded` (HTTP 403) mid-batch. If you do hit it, the
201
+ budget is spent until the next midnight-Pacific reset; report how many videos
202
+ you finished so the rest can resume after reset.
203
+
204
+ #### Bulk authoring - backfill across a set of videos
205
+
206
+ Authoring is per-video, but you often want it across many videos at once
207
+ (backfill empty descriptions, rewrite titles for a topic). Do it as a loop with
208
+ one cheap selection pass up front, not a channel-wide transcript scan.
209
+
210
+ ```bash
211
+ # 1. Select candidates cheaply (~1 unit). Weak metadata shows up in JSON fields:
212
+ ytstudio videos list -n 100 -o json # then filter client-side on:
213
+ # description == "" -> missing description
214
+ # tags == [] -> no tags
215
+ # default_audio_language == null / localizations == {} -> language gaps
216
+
217
+ # 2. Per candidate, check tracks BEFORE paying for a transcript (~50 vs ~200 units):
218
+ ytstudio videos captions <id> -o json # any standard track? any track at all?
219
+
220
+ # 3. Only if a usable track exists, pull grounding and current state:
221
+ ytstudio videos transcript <id> --lang nl -o json # ~200 units
222
+ ytstudio videos show <id> -o json
223
+
224
+ # 4. Draft on-brand, then preview each change (dry-run):
225
+ ytstudio videos update <id> --description "..." --tags a,b,c
226
+
227
+ # 5. Batch-confirm the whole set with the user, then apply each:
228
+ ytstudio videos update <id> --description "..." --tags a,b,c --execute
229
+ ```
230
+
231
+ The bulk loop and its rules:
232
+
233
+ - **Select once, author per video.** Run `videos list -o json` a single time and
234
+ filter the array yourself; do not call it per video. The fields that flag weak
235
+ metadata are `description` (empty string), `tags` (empty list),
236
+ `default_audio_language` / `default_language` (null), and `localizations`
237
+ (empty dict).
238
+ - **Gate the expensive call.** Always run `videos captions` first; skip
239
+ `videos transcript` for any video with no usable track. Captions list is ~50
240
+ units, a transcript download is ~200 - the gate is most of the quota saving.
241
+ - **Collect all dry-run previews, then ask once.** Show the user the full set of
242
+ proposed changes in one batch (not one prompt per video), get a single
243
+ go-ahead, then re-run each `videos update` with `--execute`.
244
+ - **Skip rather than invent.** Any video without a usable transcript stays
245
+ untouched and is reported to the user, per the single-video rules above; never
246
+ backfill from nothing.
247
+
145
248
  ### videos upload - batch upload from YAML sidecars
146
249
 
147
250
  `ytstudio videos upload <path>` pairs each video file with a sibling YAML
@@ -255,6 +358,8 @@ resetting at midnight Pacific. Rough costs:
255
358
  | Operation | Cost |
256
359
  |---|---|
257
360
  | Read (list/show videos, comments, playlists; analytics) | ~1 unit |
361
+ | Caption list (`videos captions`) | ~50 units |
362
+ | Caption download (`videos transcript`) | ~200 units |
258
363
  | Write (update video, moderate comment, playlist insert/reorder, schedule broadcast) | ~50 units |
259
364
  | Search (`playlists add --from-search`) | ~100 units/call |
260
365
  | Upload (`videos upload`) | ~1600 units |