--- title: What it does, and what it works with summary: Exactly what GroundSlate does on your Mac, what comes in through your agent's own connections, and the habits that keep your work findable six months later. lede: The line between your Mac and your agent's own connections eyebrow: Best practice accent: wave order: 0.5 --- GroundSlate indexes, analyses, generates, captures and renders on your Mac. Design comes from the AI agent driving it, over connections the agent already has. Apart from checking your licence and updates with coey.com, GroundSlate goes out to the network only for things you started: the weights for a local model you chose, a file at a URL your agent gives it, a web page on a site you have allowed, a call to a web service with a key you added, and a benchmark result you chose to send. ## What GroundSlate does, on your Mac - **Indexes** video, images (SVG included) and audio: shot logs, scene boundaries, summaries, place, capture date. - **Transcribes** with word level timestamps, locally. - **Recognises people** and keeps a face catalog, locally. Biometrics never reach an agent. - **Reads music**: tempo, beat grid, song structure, drops, phrase aware cut points, loudness and key. - **Speaks narration**, locally. Design a voice from a written description or pick a stock speaker, and attach it to a person or a character. Any script is then read on your Mac, identically on every run, so a timed edit stays timed. A voice can wear an effect, from a room or a telephone to a monster or a robot, on one take or on every take it speaks. - **Writes music and sound effects**, locally. Describe a bed or name a sound, and Stable Audio 3 makes it on your Mac through MLX. `generate_music` and `generate_sound_effect` return a 44.1 kHz stereo wav that goes straight into `mix_audio`, `render_cut` or `produce_reel`, saved in the library with its prompt and seed. The music is instrumental. The same prompt and seed give the same file. - **Plans cuts** from each clip's own analysis, and shows you the plan first. - **Joins clips with rendered transitions**: whips, pushes, rolls, folds and morphs. These are real camera moves, not crossfades. A second library runs inside the page: `get_kit("transition kit")` returns its files, and `list_transitions(engine=html)` lists it. - **Reframes** to a fixed canvas. `reframe_person` follows one named person's face through a clip, moving the crop every frame, and reports how much of the time it was actually on them. `make_reframe` follows the shot's main subject without identifying them, one crop per shot. - **Mixes** with a real broadcast sidechain compressor, so a bed ducks under a voice properly. - **Authors overlays** from a spec: lower thirds, location banners, callouts. - **Renders** any self contained HTML page to video, deterministically, with the bundled ffmpeg. - **Works in a browser window** on your screen. The agent opens a page at the size it will be recorded at, then clicks, types, scrolls and moves a visible pointer in it, or runs a whole timed walkthrough in one go and records it to an mp4. It can zoom the page while recording, spotlight what it is talking about, and hide or relabel parts of a page for the take. It only reaches sites you have allowed, and it will not press anything it has hidden or relabelled. - **Captures web pages** itself, rendered by WebKit on your Mac, not fetched by your agent. `capture_page` takes a still, `record_page` records an mp4, and `scroll=True` scrolls the page from top to bottom, which turns a static site into footage. `consent="reject"` dismisses a cookie banner by refusing it. There is no accept option and there will not be one: agreeing to tracking in your name is not an agent's decision. Capture is off until you turn it on, and then follows your site policy: block all, allow all, or a list you keep. An agent cannot widen that policy. It can only ask with `request_browser_site` and wait for you to decide in the app. - **Files the result** into your library and projects, or exports a clip's edit for finishing elsewhere: an EDL, an FCPXML for Final Cut, a marker CSV, YouTube chapters, and a shot and transcript index. Premiere imports the EDL. A layered cut document can also go out through `export_cut` as FCPXML or FCP7 XML. Nothing writes a Premiere project. - **Asks for your notes**: `request_review` puts a render in front of you to mark up with boxes, arrows, labels, pictures and reference files, and the agent reads your notes back. - **Shows you the frames**: an agent can pull real frames out of a composition it is still writing and out of the file it just rendered, so it has looked at the result before it calls it done. - **Grades and treats a clip** from a catalog of named looks: stocks, prints, glass, bloom, camera moves, each with its own settings and its measured cost. It also bakes a LUT from a reference clip. A second catalog runs neural models on every frame for depth and subject work, using weights you install yourself. - **Generates a shot** from a written prompt, on your Mac, through MLX. Nothing is uploaded and no key is needed. Give it a spoken line and the picture speaks it, with the clip as long as the line, within the same length limit as any other shot. Ask for a preview first and it makes the shot in about two thirds of the time; finish the one you like and you get exactly the clip a full render would have made. The clip is saved to the library with its prompt and seed, so you can run a shot you liked again. The model pack is tens of gigabytes, and each generation takes minutes of GPU time. - **Separates a sound** from a recording, as an opt-in extra on Macs where the SAM-Audio model has been installed by hand. Speaking and designing voices needs a Mac with at least 16 GB of memory, and generating video needs a Max-class chip, M3 Max or newer, with 64 GB. The reasoning and vision models are local too, on Apple's MLX by default, with Ollama supported as an alternative engine. Benchmark, in the app menu, times your Mac on the work the app ships, and sends the result to COEY only if you press Send. For a fuller local run your agent drives, see [Time your own Mac](/resources/groundslate/skills/time-your-own-mac). ## What arrives through your agent **Research.** GroundSlate fetches web pages itself. Everything else from outside the Mac comes in through the client driving it: competitor data, a CSV of prospects, a market figure someone has to stand behind, the writing itself. **Design, from a tool such as Claude Design.** GroundSlate does not design. It ships tools, not a look: a ruler that lets a page measure itself instead of hard coding positions (`get_kit("measurement kit")`), and a browser library of transitions (`get_kit("transition kit")`). `author_overlay` makes the built-in overlay cards, lower thirds and callouts with no setup; that is the starting point, not the limit. A page you wrote must be saved to disk first: `write_composition` writes it, then `preview_html` and `render_html` can open the path. Anything with real brand control is a page your design tool makes. GroundSlate renders it and can keep it as a named kit with `save_kit`, in a collection you can refer to by name. Kits were called templates in earlier releases, and the app lists them under Code Kits. **A named track.** GroundSlate writes its own beds, so an outside music model is optional. What it cannot give you is a specific song someone else wrote. That comes from a file you own, or through your agent's own connection to a music service: an MCP server or an API key the agent holds. GroundSlate analyses whatever arrives, lays it under the cut and ducks it under the voice. **A provider voice, such as ElevenLabs.** You only need one when a character must sound like a specific voice you own at a provider. GroundSlate stores the voice id on the character, so the twelfth video sounds like the first. Your agent generates the audio through its own connection to the provider and hands the file back. Everyday narration does not need this; GroundSlate speaks it locally. **Your own keys for paid services.** Add a key in the app, under Data then Provider Keys, with the address it may be sent to, what it may do there, and how many requests it may make a day, a week and a month. Saving the first key turns on the Provider gateway on that tab; switching it off stops every key at once. Keys belong to the profile you add them in. The agent calls the service through `provider_request` by the key's name. GroundSlate attaches the key on the way out, so the agent never sees it, and a clip from your library can be sent as the upload. It suits services that take the key in a request header over https and answer with text or JSON, including a public or signed link to a finished file the agent can then bring in with `fetch_media`. A reply that is itself a file, such as audio, is not passed back. Services that need an OAuth sign-in do not work. **Your camera and your screen recorder.** Everything after the capture is local. Voice and music models change every few months. Your library, your face catalog, the relationships you have recorded and the footage they describe stay on your Mac. ## Work in a project, not in a folder This habit is what keeps a library usable a year from now, instead of a Desktop full of `final_v3.mp4`. `create_project` ties people, events and clips into one body of work, with `kind` set to `personal` or `business`. Create it before you render, not after. Then commit each render to the library against that project. It appears in the project's Outputs tab, which is kept when Recent outputs is trimmed. `list_project_outputs` returns them all, newest first. Keep the working material with the project too: the script, the fact base, the shot list, and the notes a later session will need. They are not media to add or renders to commit, so they go in the project's own working folder, where the next session can read them. A good test: would you need this file if the conversation ended right now? Ask your agent to name each output as it goes. `name_video` gives a short, readable title based on the content. Once forty renders are each named for the person they are for, you can find any of them by name six months later. ## Ask it to check its own work Three results can look like success when they are not. Each has a field that tells you. - `create_project` and `add_media_to_project` return **`unresolved`**: clip references that matched nothing in the catalog and were not added. The project is created anyway. - `name_video` returns **`written`**; check that field. A clip the library has no record of returns a `_not_found` error, and nothing is written. - `quick_cut_plan` refuses the whole plan with **`unresolved sources`** instead of planning around a bad reference, so retry the ask rather than assuming it worked. "Tell me what did not resolve" is a good closing line on any ask that touches a lot of clips. ## Prefer ids to paths Clip, person and project ids survive being copied between tools. Paths do not: a path containing a non-ASCII character will not survive being retyped from another result, and the tools will say so rather than guess. Most tools accept a clip id, a filename or a bare stem as well as a path. Use the id when you have one.