sigil-youtube

YouTube Data API v3 client library for Sigil.

Provides a complete interface to YouTube's video management, upload, analytics, livestreaming, and playlist APIs.

Features

• Video management — list, update, delete videos; set custom thumbnails
• Resumable uploads — chunked upload protocol with resume-after-failure support
• Analytics — query views, watch time, subscribers, traffic sources, and top videos
• Livestreaming — full broadcast lifecycle: create, bind streams, transition states
• Playlists — CRUD for playlists and playlist items with reordering
• Search — full-text search across YouTube (quota-expensive; prefer known IDs)
• Channel info — retrieve channel metadata, subscriber counts, uploads playlist
• Quota-aware — all functions document their quota cost in comments

Modules

Dependencies

• sigil-stdlib — core, dict, string, struct
• sigil-json — JSON encode/decode
• sigil-http — HTTP client
• sigil-oauth — shared OAuth 2.0 client library

Core dependencies are from the sigil mono-repo. OAuth support is from sigil-oauth.

Building

sigil deps install
sigil build
sigil test

Usage

Create a client

(import (youtube))
;; With OAuth2 access token (required for mutations)
(define client (youtube-client access-token: "ya29.your-token"))
;; With API key only (read-only public data)
(define client (youtube-client api-key: "AIza..."))

OAuth 2.0 token management

(import (youtube oauth))
;; Create an OAuth config for Google/YouTube
(define config
 (youtube-oauth-config "your-client-id" "your-client-secret"))
;; Load stored tokens (from ~/.config/sigil/youtube/tokens.json)
(define tokens (youtube-load-tokens))
;; Build a client with auto-refresh
(let-values (((client fresh-tokens)
 (youtube-ensure-client config tokens (current-second))))
 ;; client is ready to use, tokens are refreshed if needed
 (youtube-channel-mine client))
;; Run the full authorization flow (opens browser, starts callback server)
(define tokens
 (oauth-run-authorization-flow config (current-second)))
(youtube-save-tokens tokens)

Get channel info

;; Your own channel (requires OAuth)
(define ch (youtube-channel-mine client))
(youtube-channel-title ch) ; => "System Crafters"
(youtube-channel-subscriber-count ch) ; => 50000
(youtube-channel-uploads-playlist-id ch); => "UUxxxxxxxxxxxxxx"
;; Any channel by ID
(define ch (youtube-channel-info client "UCxxxxxxxxxxxxxx"))

List and update videos

;; Get videos by ID (1 quota unit, batches multiple IDs)
(define videos (youtube-videos client "id1,id2,id3"))
;; Update video metadata (50 quota units)
(youtube-video-update client "video-id"
 #{ title: "New Title"
 description: "Updated description"
 privacyStatus: "public" })
;; Delete a video (50 quota units)
(youtube-video-delete client "video-id")

Upload a video

(import (youtube upload))
;; High-level upload (handles chunking automatically)
;; Quota cost: 1,600 units
(define video
 (youtube-upload-video client
 #{ snippet: #{ title: "My Video"
 description: "A great video"
 categoryId: "28" }
 status: #{ privacyStatus: "private" } }
 file-data
 "video/mp4"))

Query analytics

(import (youtube analytics))
;; Daily views for a date range
(define report (youtube-views-by-day client "2026年01月01日" "2026年03月25日"))
;; Top 10 videos by views
(define top (youtube-top-videos client "2026年01月01日" "2026年03月25日"))
;; Custom query
(define custom
 (youtube-analytics-query client "2026年01月01日" "2026年03月25日"
 "views,estimatedMinutesWatched,subscribersGained"
 #{ dimensions: "day" sort: "-views" }))

Manage playlists

(import (youtube playlist))
;; List your playlists
(define plists (youtube-playlists client))
;; Create a playlist (50 quota units)
(define pl (youtube-create-playlist client "New Series"
 #{ description: "Episodes of my new series"
 privacy-status: "public" }))
;; Add a video to a playlist (50 quota units)
(youtube-add-to-playlist client (youtube-playlist-id pl) "video-id")
;; List items in a playlist (1 quota unit per page)
(define items (youtube-playlist-items client "PLxxxxxx"))

Livestreaming

(import (youtube live))
;; Create broadcast + stream, bind them
(define bc (youtube-create-broadcast client
 "Weekly Stream" "2026年03月28日T18:00:00Z"))
(define st (youtube-create-stream client "Main Feed"))
(youtube-bind-broadcast client
 (youtube-broadcast-id bc) (youtube-stream-id st))
;; Get RTMP credentials
(youtube-stream-rtmp-url st) ; => "rtmp://a.rtmp.youtube.com/live2"
(youtube-stream-stream-key st) ; => "xxxx-xxxx-xxxx-xxxx"
;; Go live, then end
(youtube-transition-broadcast client (youtube-broadcast-id bc) "live")
(youtube-transition-broadcast client (youtube-broadcast-id bc) "complete")

Quota Budget

YouTube's default quota is 10,000 units/day. Key costs:

Tip: batch video IDs in youtube-videos calls — multiple IDs still cost only 1 unit.

License

BSD-3-Clause