@docyrus/animaguru 0.9.0 → 0.11.0

package/README.md

@@ -273,6 +273,16 @@ 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.
@@ -324,6 +334,47 @@ Tokens, client configuration and resumable receipts stay under `~/.config/animag
 
 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.
 
+## Cloud sync and versions
+
+CLI 0.11.0 adds `animaguru cloud` for Individual Pro and Team plans. It saves a video workspace, or a standalone video project, to AnimaGuru with every version. Use it to continue on another computer, work with your team and return to earlier versions. Personal cloud projects need your own Individual Pro or Team plan. A team's cloud projects need the team owner's Team plan, and every member can then save and download them.
+
+```sh
+animaguru auth login
+animaguru workspaces use TEAM_ID              # optional: create the cloud project in a team
+animaguru cloud link                         # creates a cloud project for this folder
+animaguru cloud push -m "First cut"          # saves a version
+animaguru cloud status                       # unsaved changes, and whether the cloud is newer
+animaguru cloud pull                         # brings in versions saved elsewhere
+animaguru cloud versions                     # newest first, with who saved each one
+animaguru cloud restore VERSION --path animations/intro/src
+animaguru cloud push                         # saves the restored files as the newest version
+animaguru cloud clone PROJECT_ID my-films    # another computer; run npm install afterwards
+animaguru cloud list
+```
+
+Run the commands anywhere inside the workspace; `--dir PATH` chooses another folder. What is not synced:
+
+- `node_modules/`, `dist/`, `production/exports/` and `production/frames/`;
+- `.env` files except `.env.example`, `.npmrc`, `*credentials*.json`, `*secrets*.json`, keys and logs;
+- anything matched by `.gitignore` or `.animaguruignore`;
+- symbolic links.
+
+Each version is a Git commit in the project's own Cloudflare Artifacts repository. Where a file is stored depends on its type, not its size:
+
+- **Media** (images except SVG, video, audio and ZIP bundles) is uploaded once by SHA-256 at any size, however many versions use it, and Git keeps a small pointer. Media counts toward the plan's media storage: 20 GB for Individual Pro and 100 GB for each team.
+- **Work files** (code, configs, briefs, JSON, SVG, fonts and everything else) are stored in Git at any size up to Artifacts' 32 MB per-file limit. A larger work file stops the push and is named; add it to `.animaguruignore` or move it.
+
+The sync store lives in `.animaguru/sync/`, separate from any Git repository you keep for the folder, and linking adds it to `.gitignore`. Git credentials are short-lived and repository-scoped.
+
+`push` refuses when the cloud has a newer version; `pull` brings it in first. Your other unsaved changes stay. When the same file changed on both sides, `pull` stops and lists it. Then:
+
+- `--prefer local` keeps yours, and the next push replaces the cloud copy;
+- `--prefer cloud` takes the cloud's, and keeps your copy in `.animaguru/sync/backups/`.
+
+`restore` makes the folder, or the `--path` files and folders, match an earlier version without rewriting history. Push afterwards to save the result as the newest version. Replacing unsaved changes requires `--yes` and keeps backups.
+
+Cloud files are never written into ignored or secret paths, through links, or outside the folder. If a plan ends, cloud projects stay readable: list, versions, pull, clone and download still work, but pushing waits until the plan is active again. `cloud unlink` stops syncing a folder without touching the cloud. `cloud delete PROJECT_ID --yes` deletes the project, all its versions and its stored files. The studio's Cloud page lists projects, versions and their files, with downloads.
+
 ## One brand, many animations
 
 ```sh