AtlatestRepositorysigil-youtube

sigil-youtube / treeREADME.md

Read it rendered

1# sigil-youtube
2
3YouTube Data API v3 client library for [Sigil](https://codeberg.org/sigil/sigil).
4
5Provides a complete interface to YouTube's video management, upload,
6analytics, livestreaming, and playlist APIs.
7
8## Features
9
10- **Video management** — list, update, delete videos; set custom thumbnails
11- **Resumable uploads** — chunked upload protocol with resume-after-failure support
12- **Analytics** — query views, watch time, subscribers, traffic sources, and top videos
13- **Livestreaming** — full broadcast lifecycle: create, bind streams, transition states
14- **Playlists** — CRUD for playlists and playlist items with reordering
15- **Search** — full-text search across YouTube (quota-expensive; prefer known IDs)
16- **Channel info** — retrieve channel metadata, subscriber counts, uploads playlist
17- **Quota-aware** — all functions document their quota cost in comments
19## Modules
21| Module | Description |
22|--------|-------------|
23| `(youtube)` | Core client, records, HTTP helpers, video/channel/search APIs |
24| `(youtube upload)` | Resumable upload protocol with chunked transfer |
25| `(youtube analytics)` | YouTube Analytics API v2 queries |
26| `(youtube live)` | Live broadcast and stream management |
27| `(youtube playlist)` | Playlist and playlist item CRUD |
28| `(youtube oauth)` | OAuth 2.0 integration via sigil-oauth (token management, auto-refresh) |
30## Dependencies
32- `sigil-stdlib` — core, dict, string, struct
33- `sigil-json` — JSON encode/decode
34- `sigil-http` — HTTP client
35- `sigil-oauth` — shared OAuth 2.0 client library
37Core dependencies are from the [sigil](https://codeberg.org/sigil/sigil) mono-repo.
38OAuth support is from [sigil-oauth](https://codeberg.org/sigil/sigil-oauth).
40## Building
42```bash
43sigil deps install
44sigil build
45sigil test
46```
48## Usage
50### Create a client
52```scheme
53(import (youtube))
55;; With OAuth2 access token (required for mutations)
56(define client (youtube-client access-token: "ya29.your-token"))
58;; With API key only (read-only public data)
59(define client (youtube-client api-key: "AIza..."))
60```
62### OAuth 2.0 token management
64```scheme
65(import (youtube oauth))
67;; Create an OAuth config for Google/YouTube
68(define config
69 (youtube-oauth-config "your-client-id" "your-client-secret"))
71;; Load stored tokens (from ~/.config/sigil/youtube/tokens.json)
72(define tokens (youtube-load-tokens))
74;; Build a client with auto-refresh
75(let-values (((client fresh-tokens)
76 (youtube-ensure-client config tokens (current-second))))
77 ;; client is ready to use, tokens are refreshed if needed
78 (youtube-channel-mine client))
80;; Run the full authorization flow (opens browser, starts callback server)
81(define tokens
82 (oauth-run-authorization-flow config (current-second)))
83(youtube-save-tokens tokens)
84```
86### Get channel info
88```scheme
89;; Your own channel (requires OAuth)
90(define ch (youtube-channel-mine client))
91(youtube-channel-title ch) ; => "System Crafters"
92(youtube-channel-subscriber-count ch) ; => 50000
93(youtube-channel-uploads-playlist-id ch); => "UUxxxxxxxxxxxxxx"
95;; Any channel by ID
96(define ch (youtube-channel-info client "UCxxxxxxxxxxxxxx"))
97```
99### List and update videos
101```scheme
102;; Get videos by ID (1 quota unit, batches multiple IDs)
103(define videos (youtube-videos client "id1,id2,id3"))
105;; Update video metadata (50 quota units)
106(youtube-video-update client "video-id"
107 #{ title: "New Title"
108 description: "Updated description"
109 privacyStatus: "public" })
111;; Delete a video (50 quota units)
112(youtube-video-delete client "video-id")
113```
115### Upload a video
117```scheme
118(import (youtube upload))
120;; High-level upload (handles chunking automatically)
121;; Quota cost: 1,600 units
122(define video
123 (youtube-upload-video client
124 #{ snippet: #{ title: "My Video"
125 description: "A great video"
126 categoryId: "28" }
127 status: #{ privacyStatus: "private" } }
128 file-data
129 "video/mp4"))
130```
132### Query analytics
134```scheme
135(import (youtube analytics))
137;; Daily views for a date range
138(define report (youtube-views-by-day client "2026-01-01" "2026-03-25"))
140;; Top 10 videos by views
141(define top (youtube-top-videos client "2026-01-01" "2026-03-25"))
143;; Custom query
144(define custom
145 (youtube-analytics-query client "2026-01-01" "2026-03-25"
146 "views,estimatedMinutesWatched,subscribersGained"
147 #{ dimensions: "day" sort: "-views" }))
148```
150### Manage playlists
152```scheme
153(import (youtube playlist))
155;; List your playlists
156(define plists (youtube-playlists client))
158;; Create a playlist (50 quota units)
159(define pl (youtube-create-playlist client "New Series"
160 #{ description: "Episodes of my new series"
161 privacy-status: "public" }))
163;; Add a video to a playlist (50 quota units)
164(youtube-add-to-playlist client (youtube-playlist-id pl) "video-id")
166;; List items in a playlist (1 quota unit per page)
167(define items (youtube-playlist-items client "PLxxxxxx"))
168```
170### Livestreaming
172```scheme
173(import (youtube live))
175;; Create broadcast + stream, bind them
176(define bc (youtube-create-broadcast client
177 "Weekly Stream" "2026-03-28T18:00:00Z"))
178(define st (youtube-create-stream client "Main Feed"))
179(youtube-bind-broadcast client
180 (youtube-broadcast-id bc) (youtube-stream-id st))
182;; Get RTMP credentials
183(youtube-stream-rtmp-url st) ; => "rtmp://a.rtmp.youtube.com/live2"
184(youtube-stream-stream-key st) ; => "xxxx-xxxx-xxxx-xxxx"
186;; Go live, then end
187(youtube-transition-broadcast client (youtube-broadcast-id bc) "live")
188(youtube-transition-broadcast client (youtube-broadcast-id bc) "complete")
189```
191## Quota Budget
193YouTube's default quota is 10,000 units/day. Key costs:
195| Operation | Cost |
196|-----------|------|
197| Read (list/get) | 1 unit |
198| Write (insert/update/delete) | 50 units |
199| Video upload | 1,600 units |
200| Search | 100 units |
201| Thumbnail upload | 50 units |
203Tip: batch video IDs in `youtube-videos` calls — multiple IDs still cost only 1 unit.
205## License
207BSD-3-Clause