@kvman/kvvideo 0.1.2 → 0.1.3

package/docs/guide.md

@@ -2,8 +2,8 @@ You can make any kind of video with the `video` connector: a lesson, an explaine
 
 Make every video through these stages, in order; each ends with what it gives the next, and a stage the request already settles takes a line (a script the person gave settles the concept). Keep a video's files in its own folder, such as `videos/<name>/`, and the video beside it.
 
-1. **Ready.** Run `video check`. When something is missing, tell the person in plain words what to install or set, and stop until it is there: ffmpeg (with libass and libfreetype) from https://ffmpeg.org/download.html; Google Chrome or Microsoft Edge; a narration service chosen on kvvideo's extension page, with its key added there as a secret (`elevenlabs.apiKey` or `openai.apiKey`), or Piper (`pip install piper-tts`) with a voice file.
-2. **Brief.** Read everything the person sent, and look at what the video is about (their app, site, or files, and the workspace's brand with `video brand`) before you ask. Then ask in one round only what is still open, your recommendation first in each: what the viewer should know or do after watching, who they are, where it will be shown (this sets the shapes and the length: a social clip is 1080 × 1920, under 60 s, and works on mute), the length, the language, and the voice (generated, or the person's own). Write the answers to `brief.md` in the video's folder.
+1. **Ready.** Run `video check`. When ffmpeg or the browser is missing, tell the person in plain words what to install, and stop until it is there: ffmpeg (with libass and libfreetype) from https://ffmpeg.org/download.html; Google Chrome or Microsoft Edge. A narration service is needed only for a video with a voice: when it is the only thing missing, go on and settle the voice in the brief. When the video has a voice (generated, or the person's own, whose examples are generated) and no service is ready, tell the person to choose one on kvvideo's extension page, with its key added there as a secret (`elevenlabs.apiKey` or `openai.apiKey`), or Piper (`pip install piper-tts`) with a voice file, and stop until it is there.
+2. **Brief.** Read everything the person sent, and look at what the video is about (their app, site, or files, and the workspace's brand with `video brand`) before you ask. Then ask in one round only what is still open, your recommendation first in each: what the viewer should know or do after watching, who they are, where it will be shown (this sets the shapes and the length: a social clip is 1080 × 1920, under 60 s, and works on mute), the length, the language, and the voice: generated, the person's own, or none (on-screen text and sound effects only). Write the answers to `brief.md` in the video's folder.
 3. **Research.** Gather the facts with their sources, the person's media, and licensed media from the web, and add them to `brief.md`. When the video shows an app of the workspace, start it in the background with `shell`, walk its flows once in the browser, and note the real labels, the selectors, and the demo data each scene needs: clean, believable data, never the person's private data.
 4. **Concept.** Write the core message in one sentence, the hook of the first 3 s, and the structure, starting from the video's kind:
    - a tutorial: the goal, each step in order, the result, what to do next;
@@ -14,18 +14,19 @@ Make every video through these stages, in order; each ends with what it gives th
    - a social clip: the payoff promised in the first 2 s, delivered fast, then a call to action.
    When the concept is open (a promotion, a story, an explainer without a script, or any video whose angle could go several ways), hand the brief in one `delegate run` to the worker that debates approaches, when the `delegate` entry lists one, asking for two or three directions, the strongest first, each with its hook, structure, and look; then offer them to the person with `ask choice`. Choose the concept yourself for a tutorial of clear steps or a script the person gave. Add the chosen concept to `brief.md`.
 5. **Treatment.** Show the person the whole video before anything costs money:
-   - a Markdown artifact: the concept in a line; "Look and sound" (the shapes, the brand, the framing, the caption style, the transitions, the sound effects, and the voice: generated, with its service, tone, and speed, or recorded by the person, with what the examples cost); a table with one row per scene: its purpose, its narration, its picture (an HTML scene, a website, an image, or a clip), its on-screen text, its motion, its transition, and its length; then the media from the web with their sources and licences;
+   - a Markdown artifact: the concept in a line; "Look and sound" (the shapes, the brand, the framing, the caption style, the transitions, the sound effects, and the voice: generated, with its service, tone, and speed, recorded by the person, with what the examples cost, or none); a table with one row per scene: its purpose, its narration, its picture (an HTML scene, a website, an image, or a clip), its on-screen text, its motion, its transition, and its length; then the media from the web with their sources and licences;
    - `style.css` in the video's folder: the colours, fonts, type sizes, spacing, and motion (easing and durations) that every HTML scene uses, from the brand;
    - one or two style frames, the title and a typical scene, as HTML scenes you checked with `video look`, each shown as an HTML artifact with `style.css` copied into a `<style>` element, since an artifact can't load the workspace's files.
-   Narration runs about 2.5 words a second in English and 2 in Arabic: each scene's narration fits its length, and the whole is within 10% of the length asked. Then ask with `ask choice`, the option that makes the video first and one that changes something. The person's agreement covers everything the treatment lists and is the go-ahead for the production map: never ask it again. When they change something, change the treatment and ask again. Save a new brand with `video brand-set` once they agree.
+   Narration runs about 2.5 words a second in English and 2 in Arabic: each scene's narration fits its length, and the whole is within 10% of the length asked. With no voice, each scene lasts long enough to read its on-screen text, and the whole is within 10% of the length asked. Then ask with `ask choice`, the option that makes the video first and one that changes something. The person's agreement covers everything the treatment lists and is the go-ahead for the production map: never ask it again. When they change something, change the treatment and ask again. Save a new brand with `video brand-set` once they agree.
 6. **Production map.** When the `execution-map` connector is listed, set a map from the treatment: the voice, the scenes, the recordings, the assembly and review, and the delivery, with scenes that can be made at once as parallel steps, and start at once.
-7. **Voice first.** Make each scene's narration before its picture: `narrate`; or, for the person's own voice, `narrate` each sentence as an example, `ask record` with one card per scene (each sentence a line, with the words to stress and where to pause), and `voice` with the takes it answers. The caption times it answers are the clock the picture follows.
+7. **Voice first.** Make each scene's narration before its picture: `narrate`; or, for the person's own voice, `narrate` each sentence as an example, `ask record` with one card per scene (each sentence a line, with the words to stress and where to pause), and `voice` with the takes it answers. The caption times it answers are the clock the picture follows. With no voice, skip this stage.
 8. **Pictures.**
    - **HTML scenes** link `style.css` and move with CSS animations and transitions only, never script timers. Time each element to its words: a page's clock starts when its recording starts and the narration 300 ms later, so an element that comes in with caption line n has an `animation-delay` of 300 ms plus that line's `startMs`. Look at each scene with `video look` at the moments that matter, and fix it before you record it. With four or more HTML scenes besides the style frames, hand them to designer workers of the `delegate` connector, one scene file each, all in the same reply: each brief, titled motion graphics designer, names `brief.md`, `style.css`, and the style frames in its context, gives the scene's row of the treatment and its caption times, and says to check the scene with `video look`; check each again with `video look` when it comes back.
    - **Websites**: `record` with the scene's `narration`, each action at its caption line with `atLine`. Mark where the eye must go with a `callout` or a `highlight` in `compose`, and `blur` anything private.
    - **Images and clips** go to `compose` as they are, a clip's part chosen with `from` and `to`.
    Then `record` each HTML scene with its `narration`.
-9. **Assemble and review.** `compose`, then `video review`, and look at every sheet against the treatment: each scene says and shows what its row says; actions land on their words; text is spelled right, readable on its background, and inside the middle 90% of the frame; nothing is cut off, overlapping, empty, or badly zoomed; the look is the same in every scene; private data is blurred; credits are there; and the review reports no problem. Fix each fault at its cause and compose again, at most three rounds; after the third, tell the person what is still wrong.
+   - **With no voice**, the on-screen text carries the words: time an HTML scene's elements from the recording's start, record a website with `wait` steps between its actions and no `narration` or `atLine`, give each scene its `durationMs` in `compose`, and leave out captions. The sound effects stay.
+9. **Assemble and review.** `compose`, then `video review`, and look at every sheet against the treatment: each scene says and shows what its row says; actions land on their words; text is spelled right, readable on its background, and inside the middle 90% of the frame; nothing is cut off, overlapping, empty, or badly zoomed; the look is the same in every scene; private data is blurred; credits are there; and the review reports no problem. Fix each fault at its cause and compose again, at most three rounds; after the third, tell the person what is still wrong. With no voice, `silence` and `loudness` problems are expected and aren't faults.
 10. **Deliver.** Make the other shapes the brief needs with `extraSizes`. Tell the person where the file is, its length, and its shapes; the chat shows a player. When they ask for a change at a time ("at 0:42"), find its scene from the video's scene times, make only that scene again, and compose again: unchanged narration comes free from the cache.
 
 How a good video looks and sounds:
@@ -34,7 +35,7 @@ How a good video looks and sounds:
 - **Look.** The same colours, type, and style in every scene, from `style.css`. For the first video, take the brand from what the person gave or what the video is about (their app's or site's styles, their logo file), or design one. Give each HTML scene a clear hierarchy, alignment, contrast, and space, with important things inside the middle 90% of the frame. Draw titles, diagrams, charts, and illustrations as HTML, CSS, and SVG; use the person's media and licensed media from the web for what drawing can't show. Show a recorded website in a `window` frame, a phone site in a `phone` frame.
 - **Motion.** Let `record` and `compose` move the pointer and the camera. In an HTML scene, enter with an ease-out of 300 to 600 ms, never linear, one thing moving at a time, and kinetic text only for the key words. Use `crossfade` between scenes, `slide` for a step forward in a sequence, and `fade-black` before the ending.
 - **Text.** Short, correctly spelled, readable on its background, and in the video's language. Arabic reads right to left in an Arabic font, with `dir="auto"` on every text element of an HTML scene.
-- **Sound.** A clear, natural voice whose `tone` and `speed` fit the purpose; names said right through the pronunciation list (`kvvideo.narration.pronunciations`). Sound effects stay on unless the person asks otherwise. There is no music.
+- **Sound.** When the video has a voice, a clear, natural one whose `tone` and `speed` fit the purpose; names said right through the pronunciation list (`kvvideo.narration.pronunciations`). Sound effects stay on unless the person asks otherwise. There is no music.
 - **Accuracy and licences.** Say only what is true: what the person gave, what was recorded, or what a source read through a connector says; no invented numbers, features, quotes, or claims. Blur emails, keys, names, and other personal data on screen. A font, library, image, or clip from the web is used only under a licence that allows it, saved in the video's folder, with its source and licence in the treatment and its credit in the end scene when the licence asks for one; pin a library's exact version.
 
 Rules:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kvman/kvvideo",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "kvvideo: the kvcoder extension that makes any kind of video, from websites and pages recorded in the browser, narrated, and captioned.",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,7 @@
   },
   "devDependencies": {
     "@kvman/kvai": "0.1.9",
-    "@kvman/kvcoder": "0.1.21",
+    "@kvman/kvcoder": "0.1.23",
     "@kvman/kvwebui": "0.1.8",
     "@kvman/sdk": "0.1.5",
     "@kvman/testkit": "0.1.10",