# Workspace > The folder that holds your videos, settings and copied media, and how files get into it. ## What a workspace is A workspace is a folder of plain files. Every project lives inside it, in its own folder, and the app writes its settings and a guide for Claude Code next to them. ``` Reels/ workspace.json marks the folder as a workspace BetterEdits.md the generated guide for Claude Code CLAUDE.md yours; it imports the guide .claude/settings.json lets Claude Code run the command line without prompts settings/ captions.json, caption-styles.json, text-styles.json projects//project.json the canvas, the brief, notes, and the media the video uses projects//timeline.json the edit: tracks, clips, texts and caption bars projects//styles.json the looks the video uses projects//media/ copied files; exports/; template.json for a video started from one; .betteredits/ (the app's own) cache/ frames/ ``` The app opens on the workspace window. Without a workspace it offers New Workspace… and Open Workspace…, and lists the workspaces opened before under Recent Workspaces. ## Create or open one - **New Workspace…** (the workspace window, or File › New Workspace…) asks for a name, a place, what you make there and where your footage lives, creates the folder and sets it up. - **Open Workspace…** opens an existing one; a folder that is not a workspace yet is offered, never converted silently. - **Close** (top of the sidebar, or File › Close Workspace) forgets the workspace and shows the empty state. Nothing is deleted. - **Show Workspace** (⇧⌘W) brings the workspace window to the front from a project. - **Reveal Workspace in Finder** opens the folder. One workspace is open at a time. Opening another one switches to it. ## Media folders Media folders decide which files are copied. - A file inside one of the workspace's media folders, or inside the workspace itself, is used where it is. - A file imported from anywhere else is copied into the project's `media/` folder first, once per project, with its `.analyzemedia` file, and stored by relative path. The project folder then moves as one piece. Add a media folder from the sidebar's Media Folders list, from File › Add Media Folder…, or with `media-folders --add` on the command line. Each project card shows its size on disk, copied media included. To stop using a folder, click the × beside it. If videos still use files from it the app asks: **Consolidate into Videos** copies those files into each video's own `media/` folder first, **Remove Anyway** leaves the references pointing at the folder, **Cancel** keeps it. > **Where to keep footage** > > Add the folder you shoot into as a media folder. A shoot is then never duplicated, while a one-off file from the Desktop still travels with its project. ## Analysed footage Claude cannot watch a video. Analysing a file once reads it and writes what was found next to it: `clip.mp4.analyzemedia` beside `clip.mp4`. It is an open format and holds a summary, the scenes and cuts, the people, every spoken word with its timing, silences, music and beats. The app reads the transcript for subtitles, and Claude Code reads the whole file to know what footage shows and says. See [Captions](https://betteredits.app/docs/captions). Analysing is a command line job, and Claude Code runs it for you: `analyze ` uploads the file to the analysis service, waits, and writes the file next to the footage. Analysis is part of Pro, which starts with a 7-day free trial. The first time, Claude runs `login`, which opens the dashboard in your browser; you sign up, start the trial, and the Mac is signed in. The credential lives in the app's own settings, never in a workspace. See [Claude Code](https://betteredits.app/docs/claude-code#analysing-footage) and [Command line](https://betteredits.app/docs/cli#analysis). You never need it. A file that has not been analysed plays, cuts and exports as usual, and the app says nothing about it. A file that has wears a small green "Analysed" label on its tile in Sources, and its preview panel shows what was found, with a button to open the file. The app reads the files again whenever it comes to the front. Older `.smartmedia` files, the format's first name, are still read. A file and its analysis move together. Copying a file into a video copies the `.analyzemedia` file; Consolidate and Export a Copy… do the same. ## Sources Everything on the timeline comes from one of two places: the video's own `media/` folder (This video) or a library (a folder of footage the workspace uses in place). A file imported from anywhere else, dropped from Finder or named in `project.json` by hand, is copied into `media/` first, so a video's folder is complete on its own while a shoot's footage is never duplicated. Texts, placeholders and subtitles are the video's own and live in its files. The Sources sidebar, the left column of the project window, shows those files as a grid of thumbnails with their lengths. The row at the top picks where from: This video, Libraries (each a folder to open, with their subfolders inside and a breadcrumb back), and Missing when files the video uses are gone from disk. A library that is missing, or that macOS does not let the app read, says so. Click a tile once and it plays in the main player, sized to its own picture, with its name top left and a close button on the right. Its own play button, time and scrubber sit under the picture; space, a click on the picture and the transport bar work too. The panel on the right shows the file: where it lives, its length, size, frame rate and sound, and, when it has been analysed, what was found: a summary, the transcript's length and language, and who wrote it when, with a button to open the file. Add to Timeline sits at the top of that panel. Esc, or any move on the timeline, brings the timeline back. Every tile shows the file's picture at its own shape, a tall strip for a portrait clip. A tile on the timeline wears a check, with a count when it is used more than once; a file that has been analysed wears a small green "Analysed" label. Drag a tile onto the timeline, or double-click it to add it to the active track at the playhead. Right-click for Add to Timeline, Open, Reveal in Finder and Export a Copy…, which copies the analysis along. Import… at the foot brings in video, photos and sound from anywhere. Drop files on This video (from Finder, or a library's tile) to copy them into the video without putting them on the timeline. Select a clip in the timeline and its file is one click away: Show in Sources in the clip's right-click menu, or the small link under the clip's name in the inspector, opens the source it lives in, walks into the library's folders down to it, scrolls to its tile and lights it up. ## Missing files A file that is no longer on disk is still a source, listed under Missing, and the video still opens. Its clips turn red in the timeline and read "Missing: file", the inspector says where the file was, and the clip plays as a plate with the file's name until the file is back. Two ways back, on the red clip's menu, in the inspector, and on the Missing tile: - **Relink…** chooses the file in a panel. Every clip of that file plays the new one from the same in and out points; a shorter file asks whether to keep it and cut the clips to its end, or choose another. A file outside this video and its libraries is copied in. - **Choose from Sources** turns the Sources sidebar into a picker: the next tile clicked stands in for the missing file. Tiles of the wrong kind (sound for a picture) are dimmed. Put the file back where it was and the app picks it up the next time it comes to the front. `lint` and `check` report missing files as warnings; the command line has `media-relink`. Settings for whatever you select sit on the right: a clip, a track, or a subtitles track with its Track and Bars tabs. The toolbar holds only Voiceover, Text, Export and Video; subtitles are generated from a track's panel. ## The Workspace panel The Video button in the project toolbar (the info icon) opens a panel with the video's name (change it there), the workspace's location, its media folders, and the media the open video uses. Each file shows its length, how many clips use it, and whether it was copied into the video. Open, Reveal in Finder and Export… are in each row's menu; Export All… copies every file somewhere else. ## Single files - **Save a Copy As…** (⇧⌘S) writes the open project as one `.be` file: the three project files in one JSON object, with absolute media paths. The project itself stays in the workspace. - **Import Project File…** (⌘O) copies a `.be` file into the workspace as a project of its own and opens it. ## The files are the edit A project is its three files. The app shows them as a timeline and writes every change back at once, in a layout made for reading: one clip per line, only the keys that matter, nothing that is an id. Edit them with any tool and the app applies the change within a second as one undo step called Edit on Disk. ``` { "tracks": [ { "kind": "text", "name": "Titles", "clips": [ { "text": "SUMMER ON THE COAST", "at": 0.4, "duration": 3, "style": "Elegant", "y": 0.3 } ] }, { "kind": "video", "name": "Video 1", "magnetic": true, "clips": [ { "media": "coast", "in": 2, "out": 5.5 }, { "placeholder": "Sunset wide", "duration": 4, "note": "golden hour, tripod" } ] }, { "kind": "audio", "name": "Music", "ducks": true, "clips": [ { "media": "song", "at": 0, "in": 0, "out": 42, "volume": 0.6 } ] } ] } ``` - `timeline.json` lists the tracks top to bottom, each with a name of its own. A clip is a `media` name from project.json with `in` and `out` in seconds of the file, a `placeholder`, or a `text`; placeholders and texts take a `duration` (3 seconds when left out) and a text a `style` (the default favorite when left out). `at` is where a clip starts on the timeline: required on a free track, left out on a magnetic one, which packs its clips in order. Subtitles tracks hold `bars` with `s`, `e` and `text`. - `project.json` holds the canvas, the brief, notes, and `media`: a name for every file the video uses with its path. Files inside the project folder are written by relative path, so the folder moves as one piece. - `styles.json` holds a look per name: font, size, colour, box, shadow, outline. A clip names one and can override any of its keys in place. - A `note` on any clip or track is kept and shown in the sidebar, never rendered. The app is strict about what it reads. A misspelt key, a media name that is not in project.json, an `out` past the end of a file, two clips overlapping on a free track, `at` on a magnetic track, or two tracks with one name is refused with the file, the place and the problem: a notice under the window title and a short message in the viewer, `problem` in the command line's `status`, and the `lint` command, which reads the files without the app and lists every problem and warning at once. The app keeps its own copy and does not write over the file until it is fixed; closing the video then asks whether to replace the files with the app's copy or discard the app's changes. The generated guide in the workspace documents every key. Caption styles, text favorites and the subtitle bar rules are the JSON files under `settings/`; those reload live too.