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-28T18: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