@docyrus/animaguru 0.8.1 → 0.10.0

package/README.md

@@ -267,17 +267,73 @@ Run `animaguru auth login`, then submit from a finished AnimaGuru video workspac
 ```sh
 animaguru submit --yes                            # Builds and hosts HTML5; private
 animaguru submit --share "alex@example.com" --yes  # Private review for a verified account
-animaguru submit --visibility public --yes         # Listed at https://animaguru.com/videos
 animaguru submit --file production/exports/film.mp4 --poster public/assets/cover.png --yes
 animaguru submit --file production/exports/film.zip --dry-run
 ```
 
 An optional positional directory selects the workspace; file and poster paths are relative to it. HTML5 exports upload the compiled animation and local media; source code, project instructions, credentials and generation receipts are not submitted. MP4 and AnimaGuru HTML5 ZIP are both supported. The CLI prints the video ID and full watch URL. Public HTML5 videos offer embed markup on the watch page; private sharing requires the selected AnimaGuru users to sign in.
 
+MP4 subtitles: CLI 0.10.0 uploads an MP4's subtitles with it, and the AnimaGuru player shows them over the picture with a CC button to turn them off and a menu when there are several languages. The MP4 itself stays clean. With the default `--subtitles auto`, `submit --file FILM.mp4` adds `FILM.vtt` (or else `FILM.srt`), which `npm run export:mp4` writes beside it. `--subtitles FILE` chooses another `.vtt`/`.srt` file and `--subtitles none` skips them. The language comes from `--subtitle-language`, a WebVTT `Language:` header, the export receipt (`FILM.json`) or `film.config.json`. The file is checked before any video bytes are sent, and the dry run lists it. An MP4's width, height and duration now come from the MP4 itself and its default title from the export receipt, so another language's cut no longer takes the current `film.config.json` values. Burned-in `--burn-captions` exports have no subtitle files, so nothing is added. To add, replace or remove one language on an uploaded MP4:
+
+```sh
+animaguru videos subtitles VIDEO_ID --file production/exports/film-tr.vtt --yes   # language from the file or its export receipt
+animaguru videos subtitles VIDEO_ID --file subtitles.srt --language de --yes
+animaguru videos subtitles VIDEO_ID --remove de --yes
+```
+
+Each upload of up to 1 MiB is stored as WebVTT, up to 20 languages per video. HTML5 films draw their own captions and take no subtitle files. New subtitles on a public video send it back for staff review, like a new poster; removing a language does not.
+
+To request public gallery publication, upload privately, open the video in My videos on the website, choose Share → Public, and accept the public video sharing agreement. Staff must approve the submission before anyone else can access its public link, download or embed. Direct CLI public-sharing requests without agreement acceptance are refused by the API.
+
 `videos list --scope mine|shared|public` lists films. Owners can edit metadata, change visibility and replace recipients on the website, or use `videos share VIDEO_ID --visibility private --share "alex@example.com" --yes`. `videos delete VIDEO_ID --yes` removes the film and files. Making a film private or removing a recipient revokes access to existing playback links.
 
 Uploads are divided into SHA-256 verified 8 MiB parts. Interrupted submissions print their video ID: inspect with `videos get VIDEO_ID`, retry a fully uploaded film with `videos complete VIDEO_ID`, or delete the unfinished draft before resubmitting. Completion is idempotent. HTML5 ZIPs allow 64 MiB compressed / 96 MiB expanded with 500 entries and 32 MiB per asset; MP4s allow 512 MiB; PNG/JPEG/WebP covers allow 2 MiB. Uploads are available to verified accounts with a 2 GiB video library allowance. Hosting does not run paid generation jobs.
 
+## Upload directly to YouTube
+
+CLI 0.9.0 adds `animaguru youtube`. Authorization and uploads run on your computer and call Google directly. You do not need an AnimaGuru account or a hosted video. The website, Worker, R2 and D1 are not involved.
+
+Enable YouTube Data API v3 in your Google Cloud project, configure the Google Auth Platform consent screen and test users, and create an OAuth client of type **Desktop app**. Download its JSON file outside your project. A web OAuth client or Gemini API key will not work. The CLI uses Google's system-browser authorization with PKCE and a temporary `127.0.0.1` callback listener. Google app verification and quota rules apply. See [Google's installed-app OAuth guide](https://developers.google.com/identity/protocols/oauth2/native-app).
+
+```sh
+animaguru youtube auth login --client-file /absolute/path/desktop-client.json --yes
+# Or, to also upload subtitles:
+animaguru youtube auth login --client-file /absolute/path/desktop-client.json --captions --yes
+animaguru youtube auth status
+# --no-browser prints the URL; open it in a browser on this same computer.
+```
+
+Login requests `youtube.upload` to send videos and `youtube.readonly` to identify and verify your selected channel. Add `--captions` to also upload subtitle tracks: YouTube's caption API requires Google's broader `youtube.force-ssl` permission, which also allows managing your videos, so it is requested only with that flag. To add it to an existing connection, log out and log in again with `--captions`. `--yes` acknowledges [YouTube's terms](https://www.youtube.com/t/terms), Google's data use under its [privacy policy](https://policies.google.com/privacy), and local credential storage. Choose your own channel in Google's authorization screen. `ANIMAGURU_YOUTUBE_CLIENT_FILE` can supply the client-file path. To switch channels, disconnect first.
+
+Export your animation with the existing `npm run export:mp4` workflow, then use the saved MP4 path:
+
+```sh
+animaguru youtube upload --file production/exports/film-en.mp4 \
+  --title "My film" --description "Made with AnimaGuru" \
+  --privacy private --made-for-kids no --synthetic-media yes --dry-run
+# After reviewing the file, destination and visibility, replace --dry-run with --yes.
+animaguru youtube upload --file production/exports/film-en.mp4 \
+  --title "My film" --description "Made with AnimaGuru" \
+  --privacy private --made-for-kids no --synthetic-media yes --yes
+animaguru youtube uploads list
+animaguru youtube uploads resume UPLOAD_ID --yes
+animaguru youtube auth logout --yes
+```
+
+Private is the default; `--privacy unlisted|public` changes it. You must choose `--made-for-kids yes|no` and `--synthetic-media yes|no` yourself. Follow [YouTube's synthetic-content disclosure guidance](https://support.google.com/youtube/answer/14328491); ordinary animation and realistic synthetic scenes can have different requirements. `--channel CHANNEL_ID` requires an exact match with your saved connection. Upload `--yes` confirms the destination, visibility and your rights to distribute the video. It does not spend AnimaGuru credits or submit it for AnimaGuru gallery review.
+
+The optional positional directory sets the root for relative paths. The default title comes from the MP4's export receipt (`FILM.json`), then the film's `film.config.json`. `--animation NAME` selects a film in a multi-animation workspace. `--file` is required; export/rendering is a separate step. MP4s can be up to 256 GiB. Titles allow 100 characters and descriptions 5,000 UTF-8 bytes; neither may contain angle brackets. `--dry-run` checks the file and metadata without sign-in, uploads or network calls.
+
+Subtitles: `npm run export:mp4` writes `FILM.srt` and `FILM.vtt` beside `FILM.mp4`. With the default `--captions auto`, the upload adds the `.srt` (or else the `.vtt`) as a caption track once the video arrives. `--captions FILE` chooses another `.srt`/`.vtt` file and `--captions none` skips subtitles. The language comes from `--caption-language`, a WebVTT `Language:` header, the export receipt or `film.config.json`. The track has no name by default, like YouTube Studio uploads; `--caption-name` sets one. `--dry-run` lists the subtitle file and language. Without caption permission, a found subtitle file is skipped with a note, and an explicitly chosen one is refused before any video bytes are sent. If adding captions fails after the video arrives, the video stays, the JSON includes `captionsError`, and `youtube uploads resume UPLOAD_ID --yes` adds them later. Burned-in `--burn-captions` exports have no subtitle files, so nothing is added to them.
+
+Thumbnail: when `film.config.json` sets `"poster"` (seconds), the export also saves that frame as `FILM.jpg`. With the default `--thumbnail auto`, the upload sets `FILM.jpg` (or `.jpeg`/`.png`) from beside the MP4 as the video's custom thumbnail; `--thumbnail FILE` chooses another JPEG or PNG up to 2 MiB and `--thumbnail none` skips it. This uses the upload permission, not `--captions`. YouTube allows custom thumbnails only on verified channels (https://www.youtube.com/verify); if it refuses, the video stays, the JSON includes `thumbnailError`, and `youtube uploads resume UPLOAD_ID --yes` retries after verification. Repeating an upload command for an already uploaded video adds subtitles or a thumbnail it does not have yet.
+
+Uploads run while the CLI is running. Progress and instructions go to stderr; the final JSON includes the YouTube video ID, watch URL and actual returned privacy. Google may still be processing the video. A saved SHA-256 fingerprint guards resumption; restore the original file if it changes. Retries query Google's saved byte position, including after a lost final response. Interrupted transfers reuse their upload ID and session; starting another upload of the same unfinished file is refused. Repeating a completed upload with identical metadata returns its receipt. An expired session requires inspecting YouTube Studio before intentionally starting a new upload. See [Google's resumable upload protocol](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol).
+
+Tokens, client configuration and resumable receipts stay under `~/.config/animaguru/youtube/`, or `ANIMAGURU_CONFIG_DIR/youtube/`, in owner-only directories (`0700`) and files (`0600`). They are never included in command JSON or sent to AnimaGuru. Treat a backup of that directory as credentials. Receipts older than 30 days are removed on the next listing/upload. Authorization is refreshed and channel identity checked when used; revoked grants remove local authorized data. Logout revokes Google access and removes local credentials/receipts while keeping your MP4s and YouTube videos. If Google cannot confirm revocation, the CLI links to [Google account permissions](https://security.google.com/settings/security/permissions). Manage published copies in YouTube Studio.
+
+Only one YouTube command may run at a time. Normal cancellation releases its lock. After a forced process kill, check that no YouTube command is running before removing `youtube/operation.lock` in the configuration directory.
+
 ## One brand, many animations
 
 ```sh