ytstudio-cli 0.4.1__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.
- ytstudio_cli-0.5.0/.github/dependabot.yml +21 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/.github/workflows/docs.yml +4 -4
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/.github/workflows/release.yml +5 -5
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/.github/workflows/test.yml +5 -5
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/.pre-commit-config.yaml +2 -2
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/PKG-INFO +5 -2
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/README.md +2 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/docs/api-quota.md +8 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/docs/index.md +4 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/docs/profiles.md +26 -1
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/docs/videos.md +71 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/mkdocs.yml +1 -1
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/pyproject.toml +3 -1
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/skills/ytstudio/SKILL.md +105 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/skills/ytstudio/references/reference.md +241 -133
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/commands/playlists.py +11 -2
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/commands/profile.py +83 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/commands/videos.py +176 -12
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/config.py +48 -4
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/conftest.py +37 -0
- ytstudio_cli-0.5.0/tests/test_captions.py +157 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_config.py +43 -1
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_playlists.py +46 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_profile.py +95 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_videos.py +107 -0
- ytstudio_cli-0.5.0/uv.lock +1552 -0
- ytstudio_cli-0.4.1/uv.lock +0 -1284
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/.editorconfig +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/.github/workflows/ci.yml +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/.gitignore +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/.python-version +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/LICENSE +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/ascii.png +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/docs/analytics.md +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/docs/comments.md +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/docs/installation.md +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/docs/livestreams.md +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/docs/playlists.md +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/docs/setup.md +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/docs/stylesheets/extra.css +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/scripts/build_docs_reference.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/scripts/build_skill_reference.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/skills/ytstudio/assets/upload-sidecar.example.yaml +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/__init__.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/api.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/commands/__init__.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/commands/analytics.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/commands/comments.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/commands/livestreams.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/commands/upload.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/main.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/registry.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/services.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/ui.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/upload_pipeline.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/src/ytstudio/version.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/__init__.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_analytics.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_api.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_comments.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_livestreams.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_main.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_registry.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_skill_reference.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_upload_command.py +0 -0
- {ytstudio_cli-0.4.1 → ytstudio_cli-0.5.0}/tests/test_upload_pipeline.py +0 -0
- {ytstudio_cli-0.4.1 → 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@
|
|
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@
|
|
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@
|
|
24
|
+
- uses: actions/checkout@v7.0.1
|
|
25
25
|
|
|
26
26
|
- name: Install uv
|
|
27
|
-
uses: astral-sh/setup-uv@
|
|
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@
|
|
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@
|
|
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@
|
|
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@
|
|
25
|
+
- uses: actions/checkout@v7.0.1
|
|
26
26
|
|
|
27
27
|
- name: Install uv
|
|
28
|
-
uses: astral-sh/setup-uv@
|
|
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@
|
|
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@
|
|
72
|
+
uses: codecov/codecov-action@v7.1.1
|
|
73
73
|
with:
|
|
74
74
|
files: coverage.xml
|
|
75
75
|
fail_ci_if_error: false
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: ytstudio-cli
|
|
3
|
-
Version: 0.
|
|
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
|
-
|
|
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.
|
|
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 |
|