# Desktop Local surface
Source: https://docs.aden.space/docs/help/apps-integrations/desktop-local-surface

The desktop app's own screens: your DAW projects and the player on one page, plus Sync, Files, Samples and the AI DAW bridge.
{/* Generated by `bun docs:publish` from docs/features/desktop-local-surface.md: edit the spec, not this file. */}

## What it is [#what-it-is]

The Local tab is the part of the desktop app that is not the web app in a
window. It knows about this machine: the DAW projects on its disk, the folders
it watches, what has synced to it, and the audio it can play without a network.

## Using it [#using-it]

The tabs across the top are **System**, **App**, **Organisations**, **Admin**
and **Links**, centered like browser tabs. Teams stay on the left. The Aden
mark there shows connection: it floats and spins while the backend session is
coming up, then a green dot when you are connected. The speaker on the right
shows what is playing on hover.

**Windows**: the caption buttons (minimize, maximize, close) sit on the far
right. Close quits Aden. On macOS, close hides to the Dock and the menu bar.

**Two surfaces side by side**: on Links, the split control sits next to back,
refresh and home. Any surface can pair with any other.

The window is a frame with the page inside it as a card. The **rail** on the
left holds System, Aden and Links (hover one for its name), with search and
**•••** at its foot. Search opens the web app's palette on Aden and the desktop
palette elsewhere. ••• is the app's own menu on every surface: update, App
settings, language, sign out, and theme and zoom on its last line; a dot on it
means an update is downloading or ready. The **player** sits at the bottom of
System, inside the page; Aden and Links have none. The title bar keeps only
the window buttons, the address controls and the sound indicator. On macOS the frame is
translucent: the desktop shows through it, blurred, in light and dark mode.
**Frame opacity** in App settings sets how much colour lies over that blur,
from none to solid.
**Rail density** in App settings makes the rail compact (48px, 32px
buttons), default (56px, 40px) or roomy (64px, 44px); every rail button,
pins included, follows it.

When Aden can't be reached, an offline button appears on the rail above
Search, with an amber dot. Its tooltip says what still works (tracks on this
Mac, synced files, cloud lists as last seen); clicking it checks again, and it
goes away as soon as Aden answers.

Press **⌘S** (Ctrl+S on Windows and Linux) for **full page**: the frame slides
away and the page fills the window. Move the pointer to an edge to bring one
piece back over the page: the top for the title bar and window buttons, the
left for the rail. ⌘S again, or "Toggle full page"
in ⌘K, brings the frame back. The choice is remembered.

The System and Links sidebars tuck away to a narrow rail: swipe left over
one with two fingers, or right anywhere to bring it back. The edge follows
your fingers and settles open or shut from where you let go and how fast.
Inside the desktop app the Aden web app draws no card of its own, since the
frame already holds the page in one. It takes the app's light or dark mode as
soon as it loads: the page announces itself (`aden-ready`) once it is
listening, and the shell answers with its theme.

The team switcher lives at the top of the sidebar on every surface: the web
app's own on Aden, the shell's on System and Links, at the same inset and
height, so switching surfaces moves nothing. Inside the desktop app the web
sidebars skip their logo and search row, which the rail already has. Back and
forward sit beside the traffic lights. The middle of the title bar is one
field: on Aden and Links pages it shows the address, opens what you type if it
is an address and searches anything else; on System it opens search (⌘K).

The sidebar shows **Playlists** as its own section under the pages, and hides
it on Samples, where the folder browser already fills that column. The
**Collections** block (Projects, Recent, Playlists) is hidden for now: Home
lists projects and recent files. When shown, it folds from
its header, and the cog beside it chooses whether every chip carries a label
or only the open one, and compact or roomy rows. Projects starts with **Add
project**, the same DAW picker as the Home tile. Beside the search box sits
the filter, the same popover the web sidebar puts over its tracks: sorting,
kind, DAW, file type, when it last changed and which folder it sits in, each
a headed section with its own reset, and Clear all in the footer.
DAWs and project file types show the installed DAW's own icon, or its drawn
logo when it is not on this Mac.

A project in the sidebar is the same as on Home: right click for the same
actions (`components/projects/ProjectActions.tsx` renders both), the cloud
glyph when it belongs to a track, and hidden or other-team projects left out.

A bar at the bottom shows what is playing on every tab, with the queue behind
its queue button. It is the web app's bar, the same components, not a copy of
them: `@aden/ui/components/player-bar` holds the layout and the transport and
`@aden/ui/components/player-queue-panel` holds the queue, and each app passes
in what differs. The chevron opens the full player as a drawer above the bar,
on every tab, capped to about two thirds of the window so a video never pushes
the projects and recents off the screen; the same chevron closes it. It is not
a second player, only a view of the one that owns the audio.

**Home** opens on your projects, searchable from the box beside the section
with the same filter popover next to it. Recent carries it too, next to its
**Synced** toggle: it replaced the strip of format chips, which could only
ever filter by extension. A file's row menu has **Add to Aden** as a submenu:
new version of a track, track documents, album documents (each a picker with
covers, the web's own picker rows), or team files straight away. Each tile is
a real project file with the icon Finder gives it, so an `.flp` and an `.als` are told apart at a glance. Click
one to open it in its DAW.

The filter itself is `components/shell/LocalFilterDropdown.tsx` over
`lib/local-filters.ts` (one state shape, one `applyLocalFilters`), built from
`@aden/ui/components/filter-sections`: the section heading, grid item, choice
grid and Clear all the web's track, album and playlist filters already use.
Those primitives moved out of `apps/web/components/entity-list/` so both apps
render the one implementation; the web file now only supplies its
translations.

* **New project** is the first tile. It launches an app on an empty session:
  every DAW opens on a blank project when started with no document, so starting
  one is launching the app. With one music app installed it goes straight
  there; with several it opens a searchable list showing each app's own icon,
  and **Choose an app…** at the bottom takes anything the scan missed.
* **The gear** holds everything about how the list is built: **Show as** (rows
  or tiles) and **Where to look** (across the machine by default, most recent
  first, or one folder you pick). Search sits beside the heading it filters,
  not at the far edge.
* **A zipped session is a project.** A `.zip` holding an `.flp`, an `.als` or
  any other session file is listed under the name of the file inside it, so the
  producer who zips everything before sending it still sees their work. A zip
  of samples is not listed. Opening one shows it in Finder or Explorer rather
  than unpacking it.
* **A project open in your DAW right now** carries a green dot and "Open", on
  Home and in the sidebar.
* **A project's menu** (hover a tile) opens it in its DAW, shows it in Finder,
  starts or links a track, or sends it as a transfer.
  * **Start track** (projects not linked yet) puts the project's card at the
    front of Suggested and scrolls to it: the same card an export gets, with
    the title, status, tags, audio export and folder choice.
  * **Link to a track** opens Files, Folders with the track picker for the
    project's folder already open. It used to land on Files, Projects, where
    the picker never mounted, so nothing appeared.
  * **Send as a transfer** zips the project's folder and gives you a link that
    expires in 30 days. It shows the folder's file count first, and when that
    count says the folder holds little more than the project file it names
    your DAW's collect-all export ("File > Collect All and Save" and so on)
    and tells you to run that first. A project file points at its audio by
    absolute path: zip it alone and it opens on the other machine with
    everything missing.

The sidebar lists your last few projects under the navigation, the way the web
app lists tracks in its own. Clicking one opens it in its DAW.

**Recent** is under the projects, and it is everything: bounces, sessions,
zips, whatever moved on this disk lately. Other files join when their name
says they belong to a release: a royalty statement, a banner, a cover or the
music video, so you can add them to a track from the same list. A bounce, the session it came from
and the zip you sent a collaborator are one afternoon's work, so they are one
list. **Synced** narrows it to the folders Aden syncs (the team folder and
every track folder), which is "what changed in the work I share"; the chips
filter it by format, several at a time. Clicking a row plays it
(or opens it, for a session), and the artwork is the play button: the icon
crossfades in on hover where your eye already is. Add to queue and Show in
Finder sit at the end of the row, and right-clicking gives the same actions in
words plus Copy path. Its gear holds **Show as** (rows or columns) and which
folders it reads: left alone
it reads Music, Downloads and Desktop, which for most people is every audio
file on the machine and almost none of it theirs. Add a folder and it reads
that one instead; add one under **Skip** to keep a sample library or a cloud
mirror out.

The full player lives in the bar's drawer, not on Home: cover on the left,
then the title, the actions and the waveform in one column beside it. **A/B** and the **loudness readout** sit
in the top-right rail, and the transport is one symmetrical row — shuffle,
previous, back 15s, play, forward 15s, next, repeat. Clicking the waveform
plays from there, even on a launch where nothing has loaded yet.

Hovering the loudness readout explains M, S and I; clicking it opens **EQ,
speed, pitch and mono**. That is the web player's own panel, not a copy: the
desktop hands its audio element to the shared audio store, so both surfaces
run the same graph and the same controls.

It has no History or Browse tabs any more: history
was a list nobody opened, and Browse pointed at a folder that Recent now
covers. The queue is not here either: it lives in the bottom bar, the way it
does on the web.

**Files** is everything about this team on this machine, and it asks one
question first. Sync and Files used to be two tabs answering the same
question: Sync owned the folder and the tracks, Files owned the list of files
inside it, and neither made sense without the other.

Until the team has a folder on this Mac, that question is the only thing on
the page: pick a folder, and Aden keeps this team's projects there and pushes
your changes back as you save. Everything below it needs that folder to exist,
so nothing below it is shown yet.

Once it is set, one card holds the folder: the path (click it to open in
Finder), what the folder holds (bytes and files, measured by walking it, per
team), how many track folders are linked to that team, when it last synced,
and what is being synced. The size is the folder as it is on disk, not the
sum of what sync downloaded: that number ignored files pulled by another Mac,
put there by hand, or linked in place, and read as 47 MB for a folder holding
a 795 MB project. `main/folder-size.ts` walks it (no symlinks, depth 24,
200,000 files, cached a minute, dropped when a sync run writes), behind
`sync_get_folder_size`. A track card's own "126 files, 795 MB in Aden" is the
cloud total from `track_projects`, which is why it says in Aden. **Sync now** sits in the same card, and
its dropdown holds everything else about that folder: what gets synced, **Live
sync**, **Sync settings**, **Change folder** and **Stop syncing this folder**.
It used to be a folder row, a separate controls row and a status line under
that: three places to look for one thing, with an **Open** button next to a
path people already read as a link.

Under it, two tabs, because tracks and files are two lists of the same folder
and stacking them meant scrolling a screen of files to reach the board:

* **Tracks** is the board and the linked folders, with the same **Filter** and
  **Display** controls the web app's entity lists have: multi-select status, DAW
  and on-this-Mac facets beside a Display popover for the view and the sort. It
  was one single-value status select buried inside Display. Layouts are
  **Recent** (one row per track in date sections, the default), **Board**,
  **List** and **Table**. Display toggles which properties show (status, on this
  Mac, BPM and key, files, size, DAW, updated) and groups Board and List by
  status or by **On this Mac** vs **In the cloud**; the choices persist per Mac.
  Every cover is a play button: the newest audio in the track's folder when it
  is on this Mac, otherwise its final or latest version streamed from Aden.
  A track with audio in Aden also gets a visible play button beside its cover
  (from the `audio_url` the track list already returns), since the hover alone
  hid it. A streamed version draws the waveform the API stores with it, as on
  mobile, instead of downloading the file to decode it. R2's CORS rule does not
  list the desktop's origins, so `src/main/storage-cors.ts` adds
  `Access-Control-Allow-Origin` to R2 GET responses in the app window and the
  player loads them with `crossOrigin`. Without it the EQ/LUFS graph heard
  silence and streamed versions played muted.
  **Sync to this Mac** on a
  card makes that track a folder inside the team folder, pulls down whatever
  the cloud already has for it, and pushes what you save in it from then on;
  the card then reads **On this Mac** and a toast says how many files landed.
  Pressing it again stops syncing and unlinks the folder, leaving the files.
  **Add file** copies files into that folder, and is only offered once the
  track has one. Each card says whether the track is on this device: a green
  dot with the folder's name, or "In the cloud only". The status is not
  repeated on the card, because the column it sits in is the status.

  One control answers that question, and it reads both halves of "local": the
  folder mapping the main process owns (`track_folder_list`) and the projects
  watcher this screen keeps in localStorage. The card used to carry two, a
  cloud-download icon by the title driven by the first and a button driven by
  the second, so a track with a linked folder showed a green check beside a
  "Sync to this Mac" button, and one with the watcher on but no folder showed
  a cloud icon beside "Synced". Open a
  track and **Compare** is there: pick two versions and hear them against each
  other, the same panel, picker, meters and audio engine the web app uses.
  **Track folders** below it are folders you already have, each linked to one
  track. **Add folder** picks one and then asks which track it is, with **No
  track yet, create one** in the same dialog. Dropping an `.flp` or `.als` on
  the app asks the same question.
* **Files** is everything Aden has for this team, whether or not it is on this
  Mac. A monitor icon means the file is here, a cloud icon means it is not.
  Search it, filter to On this Mac or In the cloud, and each row can be
  downloaded, shown in Finder, or removed from the disk (the cloud copy stays).
  **Recently synced**, **Watched folders** and **Storage on this device** are
  collapsed under it.

**Match local exports to tracks**, the one-off import that turns a folder of
MP3/WAV exports into final versions, lives in Settings under Import, and in the
command palette.

**Samples** is the sample libraries (see the sample-libraries spec).
**AI DAW** is the local MCP bridge.

**Scale the app** with Cmd/Ctrl and `+`, `-` or `0`, or from **Zoom** in the
team switcher. It scales every Aden window and survives a restart.