# Aspect Agent and MCP
Source: https://aspect.inc/docs/ai-intelligence/aspect-agent-and-mcp
Choose between Aspect's built-in assistant and an external AI assistant connected through MCP.
Aspect provides two ways to work with AI: the built-in **Aspect Agent** and **Aspect MCP** for external assistants such as Claude or ChatGPT.
Both can work with your Aspect media context, but they run in different places and are suited to different workflows.
## Aspect Agent
Aspect Agent is built directly into Aspect. Use it when you want to work with your media library without leaving the Aspect workspace.
It is the best starting point for everyday library work, including finding content and working with information already stored in Aspect.
## Aspect MCP
Aspect MCP connects a compatible external AI assistant to Aspect. After connecting, the external assistant can use supported Aspect tools and media context while you continue working in that assistant.
Use MCP when your workflow starts in Claude, ChatGPT, or another compatible client and needs access to Aspect.
MCP provides the connection and supported tools. Scheduling, background automation, and event triggers must be handled by the external assistant or another workflow service.
## Choose the right option
| Use | Choose |
| - | - |
| Work directly inside Aspect | Aspect Agent |
| Use Claude or ChatGPT with Aspect context | Aspect MCP |
| Complete everyday searches and library tasks in the Aspect workspace | Aspect Agent |
| Combine Aspect with a broader external-assistant workflow | Aspect MCP |
You can use both. Aspect Agent supports work inside Aspect, while MCP makes supported Aspect capabilities available to an external assistant.
Learn how to use the built-in Aspect Agent.
Connect a compatible external AI assistant to Aspect.
# API overview
Source: https://aspect.inc/docs/api-reference/index
Authenticate with an API key and work with your Aspect workspaces, projects, and assets over REST
The Aspect REST API gives you programmatic access to everything in your media library: workspaces, projects, directories, assets, collections, search, transcripts, metadata, comments, and share links.
All requests go to a single base URL:
```text theme={null}
https://api.aspect.inc
```
## Authentication
Aspect API keys start with `sk_`. Send your key in the `Authorization` header - the `Bearer` prefix is accepted but optional:
```bash theme={null}
curl -H "Authorization: Bearer sk_your_api_key" \
https://api.aspect.inc/users/me
```
A successful response returns the user who owns the key, which makes `GET /users/me` a quick way to verify your setup.
### Creating an API key
In the [Aspect web app](https://app.aspect.inc), open **Settings** and go to the **API Keys** page under your personal settings.
Click **Create new API Key** and give it a descriptive name.
The key value is shown only once at creation time - it cannot be retrieved again. Store it somewhere safe.
An API key acts as you: every request is checked against your own workspace and project permissions. Keep keys out of client-side code and public repositories.
You can also manage keys over the API itself: `POST /api-keys` creates a key, `GET /api-keys` lists your keys (metadata only, never the key values), and `DELETE /api-keys/{api_key_id}` revokes one.
## Resource model
Everything in Aspect lives in a simple hierarchy:
* **Workspace**: the top-level organization unit. Users belong to workspaces.
* **Project**: a container inside a workspace that holds directories and assets.
* **Directory**: a folder within a project. Directories can nest.
* **Asset**: a video, image, audio, or document file that Aspect indexes with AI.
* **Collection**: a user-curated grouping of assets and directories within a project.
When an asset is uploaded, Aspect automatically processes it with AI in the background (transcription, visual understanding, instant playback, and more) - there is no processing step to trigger via the API.
Permissions are inherited down the tree, so access granted on a project applies to the directories and assets inside it. For a deeper introduction, see [Core concepts](/docs/concepts/core-concepts).
## Request conventions
* Request and response bodies are JSON. IDs are UUIDs.
* Response codes depend on the endpoint. Check the expected status code and response body when integrating an endpoint.
* Many list endpoints are `POST` requests with a JSON body rather than `GET` - for example `POST /assets/list` and `POST /directories/list` take a required `parent_id` plus optional `limit`, `offset`, `filters`, and `sorts`. Other lists use `offset`/`limit` query parameters.
For example, listing the assets in a directory:
```bash theme={null}
curl -X POST https://api.aspect.inc/assets/list \
-H "Authorization: Bearer sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{"parent_id": "6c8e9a1f-0b0e-4a6a-9c94-1f2d3e4a5b6c", "limit": 50}'
```
## Endpoint reference
The per-endpoint reference is being reworked and will return here soon.
## Beyond REST
Connect Claude, ChatGPT, Cursor, or any MCP client to your Aspect library through our hosted MCP server.
# MCP server
Source: https://aspect.inc/docs/api-reference/mcp
Connect your AI tools to search and organize media, read transcripts, and collaborate in Aspect
Aspect hosts a remote [Model Context Protocol](https://modelcontextprotocol.io) server, so AI tools you already use can search and organize your media, read transcripts and document text, and collaborate on your media library:
```text theme={null}
https://api.aspect.inc/mcp
```
It is a Streamable HTTP MCP endpoint. MCP tools use Aspect's operation layer and follow the permissions of the authenticated user. For Aspect's built-in experience, see [Aspect Agent](/docs/asset-intelligence/ask-aspect).
## Authentication
Two options:
* **OAuth sign-in**: clients that support MCP OAuth (Claude, ChatGPT, Cursor, and others) prompt you to sign in to your Aspect account when you add the server. This is the easiest path.
* **API key**: send an Aspect API key (`sk_...`) as a Bearer token in the `Authorization` header. Use this for clients or scripts that can attach explicit headers. See the [API overview](/docs/api-reference/index) for how to create a key.
Either way, every tool call is checked against your own workspace, project, directory, collection, and asset permissions - the MCP server can never do more than you can.
## Connecting a client
1. In Claude Desktop or claude.ai, open **Settings**, then **Connectors**.
2. Click **Add custom connector**.
3. Paste the Aspect server URL: `https://api.aspect.inc/mcp`
4. Click **Connect** and sign in to Aspect when prompted.
1. Open **Settings** and turn on **Developer mode** (Connectors).
2. Add a new connector / MCP server.
3. Paste the server URL: `https://api.aspect.inc/mcp`
4. Sign in to Aspect when prompted.
1. Open **Settings**, then **MCP**, and add a new server (or edit `~/.cursor/mcp.json`).
2. Add the configuration below.
3. Sign in to Aspect when prompted.
```json theme={null}
{
"mcpServers": {
"aspect": {
"url": "https://api.aspect.inc/mcp"
}
}
}
```
Add Aspect as a remote (Streamable HTTP) MCP server and authorize with your Aspect account when your client prompts you:
```json theme={null}
{
"mcpServers": {
"aspect": {
"url": "https://api.aspect.inc/mcp"
}
}
}
```
If your client does not support OAuth sign-in, configure an `Authorization: Bearer sk_...` header with your API key instead:
```json theme={null}
{
"mcpServers": {
"aspect": {
"url": "https://api.aspect.inc/mcp",
"headers": {
"Authorization": "Bearer sk_your_api_key"
}
}
}
}
```
The same setup instructions are available in the web app under **Settings → Aspect Agent & MCP**, with copyable snippets per client.
## Available tools
### Workspaces
| Tool | Description |
| - | - |
| `workspaces_list` | List workspaces available to you. |
| `workspaces_get` | Get a workspace you can view. |
| `workspaces_update` | Update a workspace you can edit. |
| `workspaces_users_list` | List people in a workspace, including roles and project permission counts. |
| `workspaces_users_add` | Add people to a workspace with workspace roles. |
| `workspaces_users_update` | Update workspace roles for people. |
| `workspaces_users_remove` | Remove people from a workspace, including their project permissions. |
| `workspaces_users_all_project_access_list` | List a person's project access: effective roles, project defaults, and explicit overrides. |
### Projects
| Tool | Description |
| - | - |
| `projects_list` | List projects in a workspace you can view. |
| `projects_get` | Get projects by ID. |
| `projects_create` | Create projects in a workspace you can edit. |
| `projects_update` | Update projects you can edit. |
| `projects_users_list` | List people with access to a project, including inherited versus explicit roles. |
| `projects_users_add` | Add people to a project with project roles. |
| `projects_users_update` | Update project roles for people. |
| `projects_users_remove` | Remove explicit project permissions. Workspace members revert to the project default role; limited members lose project access. |
For files and folders at the top level of a project, call `projects_get` and use its `root_directory_id` as the parent directory ID.
### Directories
| Tool | Description |
| - | - |
| `directories_list` | List child directories under a directory you can view. |
| `directories_get` | Get directories by ID. |
| `directories_create` | Create child directories under directories you can edit. |
| `directories_update` | Rename or recolor directories. |
| `directories_delete` | Move directories to the project trash. |
| `fs_items_move` | Move assets, directories, and symlinks to a destination directory. |
| `fs_items_copy` | Copy assets, directories, and symlinks into a destination directory via an asynchronous copy job. |
Copies can go to another project in the same workspace. When copying across projects, values of project-specific metadata fields and matches to project-specific entities or objects do not carry over. Destination name conflicts are resolved by adding a suffix to the copy's name.
### Assets
| Tool | Description |
| - | - |
| `assets_list` | List assets under a parent resource you can view. |
| `assets_get` | Get assets by ID. |
| `assets_update` | Rename assets (the new name must include the file extension). |
| `assets_delete` | Move assets to the project trash. |
| `assets_document_get` | Get extracted text from a document asset (PDF, slide deck, spreadsheet, and more), optionally selecting specific page numbers. |
| `assets_timecode_get` | Convert positions in seconds to a video's SMPTE timecodes, matching the Aspect player and using the recorded source start timecode when available. |
Timecode conversion accepts multiple positions for one asset in a single call. If the asset has no frame rate usable for timecode, the tool returns null timecodes with a reason.
### Search
| Tool | Description |
| - | - |
| `assets_search` | Search a project or a single asset using visual, transcript, document, and filename signals plus metadata filters; results include matched clip timing. |
| `assets_search_capabilities` | List available search channels, filterable metadata attributes, valid filter clauses, and selectable option, Face, and user IDs. |
Use `assets_search_capabilities` before building metadata or Face filters. Use `entities_list` to look up the recognized people you want to search for.
### Transcription
| Tool | Description |
| - | - |
| `assets_transcription_get` | Get an asset's transcript, optionally scoped to a start and end time. |
### Asset content
| Tool | Description |
| - | - |
| `assets_content_get` | Read indexed scene captions and speech together in time order for video, image, or audio assets. Filter to visual or transcript entries, or a time range. |
Content and transcript tools return indexed information. `assets_content_get` returns no entries when the asset has not been processed or has no content for the requested track.
### Collections
| Tool | Description |
| - | - |
| `collections_list` | List collections in a project you can view. |
| `collections_get` | Get collections by ID. |
| `collections_create` | Create collections in projects you can edit. |
| `collections_update` | Update collections you can edit. |
| `collections_delete` | Delete collections where you have full access. |
| `collections_items_add` | Add asset or directory items to a collection. |
| `collections_items_remove` | Remove asset or directory items from a collection. |
### Metadata
| Tool | Description |
| - | - |
| `metadata_attributes_list` | List metadata attributes available in a project, including custom fields. |
| `metadata_attributes_get` | Get metadata attribute details. |
| `metadata_attributes_create` | Create custom metadata attributes. |
| `metadata_attributes_update` | Update custom metadata attributes. |
| `metadata_attributes_delete` | Delete custom metadata attributes. |
| `asset_metadata_get` | Get custom metadata values for an asset. |
| `asset_metadata_set` | Set custom metadata values on an asset. |
### Comments
| Tool | Description |
| - | - |
| `comments_get` | Get comment threads on resources you can comment on, including replies. |
| `comments_search` | Search project comments, with filters for resources, people, resolution state, timestamps, and more. |
| `comments_create` | Create plain-text comments or replies on assets, including private/internal comments, video time ranges, and document pages. |
Comment creation does not support drawing annotations, text highlights, mentions, or attachments.
### Share links
| Tool | Description |
| - | - |
| `share_links_create` | Create share links for assets, directories, or collections you fully control. |
| `share_links_list` | List share links for one resource or a whole project. |
| `share_links_update` | Update share links you can manage. |
| `share_links_delete` | Delete share links you can manage. |
Created and listed links include a `client_url`. Asset share links also include an `embed_url` for embedding the asset in an external site.
### Other
| Tool | Description |
| - | - |
| `entities_list` | List labeled entities (such as recognized people) available for a workspace or project. |
| `notifications_list` | List your in-app notifications, including comments, mentions, and replies, filtered by read state. |
| `recents_list` | List recently accessed resources in a workspace, most recent first, with pagination. |
## What MCP does not expose
MCP does not currently provide:
* **File transfers**: no upload endpoints, direct download URLs, or storage tokens.
* **Workspace creation or deletion, project deletion, or permanent file deletion**: asset and directory delete tools move items to the project trash. There is no tool to empty trash or permanently delete assets or directories.
* **Public share sessions**: share password reveal and public share sessions are not available.
Use the [REST API](/docs/api-reference/index) for these workflows.
For file transfers and operations outside this tool list, see the [REST API](/docs/api-reference).
# SDKs
Source: https://aspect.inc/docs/api-reference/sdks
Official Aspect SDKs are being reworked and are not currently published
Official Aspect SDKs for Node.js and Python are being reworked and are not currently published. In the meantime, integrate directly against the REST API with any HTTP client, or connect an AI tool through the [MCP server](/docs/api-reference/mcp). This page will be updated when the new SDKs ship.
Base URL, authentication, and request conventions for the Aspect REST API.
# Desktop app
Source: https://aspect.inc/docs/apps/desktop
The full Aspect experience on macOS and Windows, with faster transfers, tabs, and your projects mounted as a local drive.
The Aspect desktop app is available for **macOS and Windows**. It gives you everything from the web app at [app.aspect.inc](https://app.aspect.inc), running as a native app on your computer. Same projects, same search, same viewer - plus capabilities a browser can't offer.
[Download Aspect for macOS or Windows](https://aspect.inc/download), install the version for your operating system, and sign in to your Aspect account.
## Why use the desktop app
Uploads and downloads run in the app itself rather than a browser tab, so large files and big folder uploads keep moving in the background while you work.
Open your Aspect projects as a drive in Finder on macOS or File Explorer on Windows, and work with your files in native apps like Premiere Pro. See the [mounted drive guide](/docs/instant-access/mount-a-project).
Open multiple projects, folders, or assets side by side in tabs, with the keyboard shortcuts you already know from your browser.
The app updates itself automatically, so you're always on the latest version without reinstalling.
## Working with tabs
The desktop app has a tab bar, just like a browser. You can:
* Open a new tab and keep several parts of your workspace visible at once - for example, a search in one tab and a review session in another.
* Switch, reorder, and close tabs with familiar keyboard shortcuts (new tab, close tab, jump to a specific tab, jump to the last tab).
* Navigate back and forward within each tab independently.
## Transfers that keep going
Uploading and downloading is where the desktop app really pulls ahead of the browser:
* Drag in entire folders - the app walks through everything inside and uploads it all, keeping the folder structure intact.
* Transfers continue in the background while you browse, search, and review.
* Your transfer history is saved, so you can check what finished and what's still in flight.
## The mounted drive
The desktop app also manages the [mounted drive](/docs/instant-access/mount-a-project): your Aspect projects appear as a drive in Finder on macOS or File Explorer on Windows, files download only when you open them, and changes you save sync back to Aspect. You mount and unmount projects, pin files for local access, and control how much disk space Aspect uses - all from inside the desktop app.
## Signing in
When you first open the app, it sends you to your browser to sign in, then brings you straight back. Your desktop session is independent from your browser session - signing out of one doesn't sign you out of the other.
## Next steps
Browse your whole project in Finder or File Explorer and edit footage directly in your creative tools.
All the ways to get files into Aspect.
# How AI indexing works
Source: https://aspect.inc/docs/asset-intelligence/ai-indexing
The moment a file is uploaded, Aspect's AI starts making it searchable, playable, and ready to review - automatically.
## It starts the moment you upload
As soon as a file finishes uploading, Aspect's AI begins processing it. You don't need to tag, label, or configure anything - it happens on its own, in the background, while you keep working.
Results appear as they're ready. A file's transcript might show up while the rest of its processing is still finishing.
## What you get
Every spoken word in your videos and audio files becomes a transcript you can read, search, and click to jump playback to that exact moment.
Aspect understands what's happening on screen, so you can find a moment by describing it in your own words - "drone shot over the coastline" or "close-up of hands typing."
Aspect recognizes the people who appear in your footage, so you can find every shot of a specific person.
Resolution, duration, camera details, and other technical properties are read from every file automatically and made filterable.
Together, these power [Search](/docs/asset-intelligence/ai-search) - one search box that finds moments by what was said, what's on screen, who's in the shot, or what a file is called.
## Instant playback
Aspect also prepares every file for smooth viewing, so playback starts immediately even for very large originals - and you can hover-scrub a video thumbnail to skim it without opening it. Documents open and render right away, page by page.
Your original files are never modified, and you can always download them exactly as uploaded.
## What each file type gets
* **Videos**: searchable speech, visual search, people, metadata, and instant playback.
* **Images**: visual search, people, and metadata.
* **Audio**: searchable speech, metadata, and instant playback.
* **Documents**: viewable page by page, with all their text searchable.
## Tracking progress
You can see how processing is going at any time:
* Files that are still processing show an indicator in the project view.
* Open a file to see what's ready and what's still in progress.
Search results get better as processing completes. If a file was uploaded moments ago, give it a little time before expecting it to show up in search.
## When files change
If you replace a file with a new version of its content, Aspect automatically re-processes it so everything - transcript, search, playback - reflects the new file. There's nothing you need to trigger.
# AI Search
Source: https://aspect.inc/docs/asset-intelligence/ai-search
Find files and exact moments by describing what appears or is said in plain English.
AI Search helps you find content without remembering filenames, adding tags, or knowing the exact words used in a video.
Describe the shot, quote, person, place, or file you need. Aspect searches visual content, spoken words, people, tags, filenames, and metadata, then returns the files and exact moments that best match your request.
## Search by title
Use a known filename or title when you want to locate a specific asset.
## Before you search
Aspect can search an asset after AI indexing finishes. Indexing begins automatically after upload and usually takes a few minutes, depending on the size and length of the file.
You can check the processing status on each asset. If a recently uploaded file does not appear in search results, confirm that its AI indexing is complete.
Add files and learn what happens after upload.
## Search for a specific asset
Open **Search** and describe the shot, quote, person, place, campaign, or file you want to find.
You can combine visual details, spoken topics, people, dates, and metadata in the same request.
Aspect translates your request into filters you can inspect and adjust. Refine a filter if the results are too broad, or remove one to expand the search.
Results appear at the exact time ranges where a match occurs, not only as whole files. Preview a result to confirm that it contains the moment you need.
Open a result in the viewer, add it to a collection, or right-click it and select **Open in mount** to reveal the original file on your desktop.
### Search by title
## What AI Search understands
Aspect combines several kinds of information when searching your media.
### Visual content
Aspect analyzes what appears on screen, including subjects, objects, actions, locations, settings, and visual composition.
You can describe a visual moment even if nobody says those words and the file has never been manually tagged.
### Spoken content
Aspect automatically creates [transcripts](/docs/asset-intelligence/ai-transcription) for video and audio files. Dialogue, interviews, quotes, and other spoken moments become searchable without manual logging.
You can search for an exact phrase or describe the topic you remember:
* `interview clips where someone mentions the budget`
* `someone talking about delivery dates`
Opening a transcript match takes you to the relevant moment in the file.
### People
Aspect can recognize people your team has configured using reference images. Once someone is configured, their name can be used in searches and filters.
For example, you could search for `shots from last week where Harry drives the blue car`.
Aspect can create filters for the person, date range, vehicle, and matching visual scenes.
### Tags and metadata
AI Search can use:
* Automatically generated tags
* Custom labels defined by your team
* Filenames
* File types
* Dates
* Technical properties
* [Custom metadata fields](/docs/workflows/metadata)
This lets you combine content and file details in one request, such as `sunset driving shots from last month recorded at 60 fps`.
## Write a better search
Start with the most important detail, then add context if the results are too broad.
A useful query can combine:
* **Subject:** a person, animal, vehicle, or object
* **Action:** walking, presenting, driving, laughing, or opening a door
* **Setting:** a beach, office, stage, street, or studio
* **Visual style:** wide shot, close-up, handheld, daylight, or sunset
* **Spoken topic:** a product name, budget, deadline, or interview question
* **File details:** date, media type, filename, frame rate, or custom metadata
For example, start with `wide shots of a car driving through the city at night`.
If that returns too many results, add another detail: `wide shots of a blue car driving through the city at night in the rain`.
Search using the details you actually remember. You do not need to guess which tags or metadata fields already exist.
## Adjust search filters
Aspect turns a plain-English request into filters you can inspect and edit.
Use the generated filters to:
* Narrow results to a person, date range, or file type
* Combine visual matches with metadata and technical properties.
* Filter by folder path, including subfolders or only assets directly in the selected folder.
The filters show how Aspect interpreted your request, so you can correct anything that does not match your intent.
## Understand search results
Results identify the matching file and the specific time range where the match occurs.
* **Green:** stronger match
* **Yellow:** possible match
* **Red:** weaker match
Confidence represents how closely the result matches your search. It does not guarantee that the result is correct, so review lower-confidence matches when your query is broad or visually complex.
## Work with search results
### Open the matching moment
Select a result to open the asset in the viewer at the matching moment. From there, you can play the surrounding footage, inspect its transcript, or [leave a comment](/docs/review-and-approve/commenting).
### Open the original file
To work with a result in an editing application:
1. Right-click the search result.
2. Select **Open in mount**.
3. Open the original file from Aspect's mounted drive.
Aspect streams the parts of the file your application needs instead of requiring you to download the entire file first.
Stream and edit large cloud files through a drive on your computer.
### Add results to a collection
To gather related results without moving the original files:
1. Select the results you want to keep.
2. Add them to a new or existing collection.
3. Open the collection to review, organize, or share the selected content.
Collections are useful for selects, review rounds, client deliveries, research, and groups of related footage.
Group related assets without changing where the original files are stored.
## Search in archived projects
Archiving a project moves it to the **Archived** section on the workspace homepage. Its files remain indexed and searchable. Open the archived project list, select the project, and search its media as usual.
Archiving leaves the project's storage tier unchanged. To use **Open in mount** on a search result, the project must use **Active Storage**. See [storage tiers and project archiving](/docs/concepts/core-concepts#storage-tiers).
## AI Search and Aspect Agent
AI Search and Aspect Agent serve different purposes:
* **AI Search** retrieves matching files and moments.
* **Aspect Agent** can answer questions and complete multi-step tasks, such as finding content, building collections, organizing assets, editing metadata, or creating share links.
Use AI Search when you want to inspect and refine results yourself. Use Aspect Agent when you want Aspect to complete a broader task using those results.
Ask questions about your media and have Aspect complete multi-step actions.
## AI processing and privacy
AI-generated metadata is logically isolated by workspace and is not shared across customers. Your media is not used to train Aspect's or its AI service providers' models.
Folders and projects can be excluded from AI indexing.
## Related guides
Learn how speech becomes a searchable, time-linked transcript.
Open matching moments, inspect transcripts, and leave feedback.
Save groups of search results without moving the originals.
Ask questions and automate multi-step media workflows.
# AI Transcription
Source: https://aspect.inc/docs/asset-intelligence/ai-transcription
Automatically turn speech in video and audio into searchable, time-linked transcripts in 160 languages.
Aspect automatically transcribes speech in your video and audio files. There is no separate transcription job to configure and no transcript file to upload.
Add a file to Aspect and transcription begins automatically in the background. When the transcript is ready, you can read it alongside the media, search for spoken words, and click any word to jump to that exact moment.
## Video transcription
Open the transcript beside the media to read, search, and jump to spoken moments.
[Upload a video or audio file](/docs/getting-started/uploading-and-organizing) to an Aspect project. You can add an individual file or upload an entire folder.
Aspect begins processing the file automatically after the upload finishes.
Aspect creates the transcript in the background. You do not need to start transcription manually.
Processing time depends on the size and length of the file. You can continue working while transcription runs.
Select the video or audio file to open it in the viewer.
Select the **Transcript** tab to see everything that was said.
The transcript follows playback and highlights the current words as the media plays.
A transcript may become available before the rest of the file finishes AI indexing. Search results continue to improve as processing completes.
## 160 supported languages
Aspect automatically transcribes video and audio in 160 languages.
Upload your media and Aspect creates a searchable, time-linked transcript automatically. There is no transcription job to create or language-specific workflow to start.
Once processed, spoken content becomes available in the transcript, AI Search, and Aspect Agent.
## Follow playback with the transcript
The transcript is connected directly to playback.
Use it to:
* Read along while the file plays.
* Find a quote without scrubbing through the entire file.
* Click any word to jump to that exact moment.
The transcript stays synchronized as you play, pause, or move through the media.
## Search within a transcript
Use transcript search when you know a word, name, phrase, or topic that was discussed in the current file.
Open a video or audio file and select the **Transcript** tab.
Search for the word or phrase you remember.
Step through each matching result in the transcript.
Select a match to move playback to the moment where it was spoken.
## Export a transcript
You can export a transcript when you need to use it outside Aspect as VTT, SRT, TXT, and Markdown.
Open the video or audio file containing the transcript.
Select the **Transcript** tab.
Choose the transcript export option and save the transcript to your computer.
Exported transcripts can be used for interview notes, production documents, quote selection, accessibility workflows, and other tasks outside Aspect.
## Speaker detection
Aspect automatically detects speakers while creating a transcript.
Speaker detection makes interviews, meetings, panels, podcasts, and other conversations easier to follow. It also gives AI Search and Aspect Agent more context when working with spoken content.
## Search spoken content across files
Transcript search finds words inside the file you currently have open.
Use AI Search when you want to find spoken content across the project. You can search for an exact phrase or describe the topic you remember.
Example searches include:
* `interview clips where someone mentions the budget`
* `conversations about the product launch`
* `the CEO discussing next quarter`
AI Search returns matching files and takes you to the relevant moment inside each one.
Find spoken and visual moments across your media using plain English.
## Ask questions about transcripts
Aspect Agent can read and compare transcripts across the current project.
Use Aspect Agent when you want to do more than find a phrase:
* `Summarize the main points from this interview.`
* `What concerns did people raise about the launch date?`
Aspect Agent can combine transcript information with visual analysis, filenames, metadata, comments, folders, and collections.
Ask questions and reason across multiple transcripts.
## Track transcription progress
Files that are still processing show an indicator in the project view.
Open an asset to see what is ready and what is still in progress. Transcription may finish before visual analysis, metadata extraction, or other indexing tasks.
If a recently uploaded file does not have a transcript yet:
* Confirm that the upload finished.
* Check the asset's processing status.
* Allow additional time for long video or audio files.
* Refresh the asset after processing completes.
Find files and matching moments using spoken and visual content.
## When a file changes
If you replace a file with a new version, Aspect automatically processes the updated content again.
The transcript, search results, playback copy, and other generated information update to reflect the new file. You do not need to start transcription again manually.
Your original file is never modified during transcription or AI indexing.
## AI processing and privacy
AI-generated metadata is logically isolated by workspace and is not shared across customers. Customer media is used to provide the requested AI features, not to train Aspect's or its AI service providers' models.
Folders and projects can be excluded from AI indexing.
Learn more at [trust.aspect.inc](https://trust.aspect.inc/).
## Related guides
Add files and learn what happens after upload.
Search spoken and visual content across your media.
Ask questions and reason across multiple transcripts.
Play media, follow transcripts, and leave feedback.
# Aspect Agent
Source: https://aspect.inc/docs/asset-intelligence/ask-aspect
Use Aspect Agent to answer questions, organize media, and take actions inside Aspect.
Aspect Agent is built into Aspect. It understands the indexed content in your project, including visual analysis, [transcripts](/docs/asset-intelligence/ai-transcription), filenames, [metadata](/docs/workflows/metadata), [collections](/docs/share-and-present/collections), folders, and [comments](/docs/review-and-approve/commenting).
**Unlike [AI Search](/docs/asset-intelligence/ai-search)**, which returns matching files and moments for you to browse, Aspect Agent can reason across multiple results and take actions on your behalf.
## See Aspect Agent in action
These examples show how Aspect Agent can work across your media and return useful results.
## Aspect Agent and AI Search
Use **AI Search** when you want to describe a file or moment and browse the matching results yourself.
Use **Aspect Agent** when you want to:
* Ask a question that requires reading or comparing multiple files.
* Summarize information across transcripts or documents.
* Find content and organize the results.
Aspect Agent may take longer than AI Search because it can run several searches, inspect transcripts and metadata, reason across the results, and complete multiple actions.
## Before you start
Aspect Agent works with information available in the current project. Media must finish AI indexing before Aspect Agent can use its transcripts, visual analysis, and other generated information.
## Use Aspect Agent
Open the project containing the files, folders, collections, comments, or metadata you want Aspect Agent to work with.
Select **Aspect Agent** to open the Aspect Agent sidebar.
Tell Aspect Agent what you want to find, understand, organize, or change.
Include a folder, collection, date range, file type, or other scope when it helps clarify the request.
Aspect Agent shows the searches, filters, and other steps it performs. Review the returned assets, answer, or proposed action.
Ask a follow-up question, narrow the scope, correct an assumption, or tell Aspect Agent what to do with the results.
## Find and understand content
Aspect Agent can search indexed media, inspect transcripts and metadata, read documents, and reason across multiple results.
Try requests such as:
* `Find every interview where someone discusses the budget and summarize the concerns.`
* `What does the CEO say about the product launch in the keynote recording?`
# MCP
Source: https://aspect.inc/docs/asset-intelligence/mcp
Connect an external AI assistant to your Aspect media library.
Aspect MCP lets supported external AI assistants work with your Aspect media library. Use it when you want to search, summarize, organize, or manage Aspect content from a tool such as Claude or ChatGPT instead of using Aspect Agent inside Aspect.
Connecting MCP gives the external assistant access to Aspect tools and media context within your permissions. It does not create an automation or scheduled workflow by itself.
## Before you start
You need:
* An Aspect account with access to the projects and assets you want to use.
* A supported MCP client, such as Claude or ChatGPT.
* Permission to add a custom connector or MCP server in that client.
The Aspect MCP server is:
`https://api.aspect.inc/mcp`
## Connect an external AI assistant
Open the connectors, integrations, or developer settings in Claude or ChatGPT.
Add a custom connector or MCP server and enter `https://api.aspect.inc/mcp`.
Follow the authorization prompt and sign in with the Aspect account you want the assistant to use.
Confirm that the assistant can see the expected Aspect tools and only the projects available to your signed-in account.
In ChatGPT, custom MCP connections may require Developer mode. Availability can depend on your ChatGPT plan and workspace settings.
## What you can do
Use an external assistant to:
* Find assets, folders, collections, comments, and metadata.
* Read transcripts and extracted document text, then summarize or compare results.
* Create [comments](/docs/review-and-approve/commenting), [collections](/docs/share-and-present/collections), [metadata updates](/docs/workflows/metadata), and [share links](/docs/share-and-present/sharing-and-permissions) when the connected account has permission.
## Scheduling and automations
MCP provides the connection between your AI assistant and Aspect. Scheduling, recurring checks, and event triggers come from the AI assistant or an external workflow service.
Scheduled checks run periodically and are not instant event triggers. For workflows that must start immediately when something happens, use an approved API or webhook workflow.
## Permissions and approvals
MCP actions follow the permissions of the Aspect account used to connect. Use an account with only the access needed for the workflow.
Review high-impact actions before approving them, especially:
* Archiving or moving many assets.
* Creating public or expiring share links.
* Changing metadata across many files.
* Changing project access or membership.
## Current limitations
Aspect MCP does not currently provide tools for:
* Uploading or downloading files.
* Permanently deleting assets.
* Deleting an entire project or workspace.
* Moving assets directly into cold storage.
Cold archive remains a manual action in Aspect unless your team has an approved API workflow.
## Aspect Agent or MCP?
Use the [**Aspect Agent**](/docs/asset-intelligence/ask-aspect) when you want to work inside Aspect with the current project and review actions in the Aspect interface.
Use **MCP** when you want to work from an external AI assistant or connect Aspect to a broader scheduled workflow.
# Authentication and API keys
Source: https://aspect.inc/docs/cli/authentication
Use your signed-in Aspect desktop account, store an API key for a CLI-only machine, or authenticate headless jobs through the environment.
The CLI uses your Aspect identity and its existing permissions. On a workstation with the desktop app, sign in to the app. On a machine without it, use an API key.
## With the desktop app
Open Aspect and sign in, then run:
```bash theme={null}
aspect auth status
aspect ls
```
The CLI uses the signed-in desktop account automatically. You do not need to create a key for this workflow.
A signed-in desktop session takes precedence over both an environment API key and a stored key. `aspect auth status --json` reports the source as `desktop`, `env`, or `auth-file`, and reports a key that is set but ignored. An offline signed-in desktop session does not silently switch to the key's account.
## Create an API key
Use a key for a Linux server, render worker, CI job, or another CLI-only installation.
1. Sign in to the [Aspect web app](https://app.aspect.inc).
2. Open **Settings → API Keys**.
3. Choose **Create new API Key** and give it a name that identifies its use.
4. Copy the key, which begins with `sk_`. The full key is shown once.
Each key acts as the user who created it and inherits that user's access. Key creation currently accepts a name; it does not let you restrict a key to a project, folder, or read-only role. Choose the account used for an automated workflow accordingly.
## Sign in on a CLI-only computer
Run this in an interactive terminal and paste the key at the hidden prompt:
```bash theme={null}
aspect auth login
aspect auth status
```
`auth login` validates and stores an API key. It is not a browser sign-in flow. The default stored-key file is `~/.aspect/cli/auth.json`; treat it as a credential file.
If the CLI asks you to open or sign in to the installed Aspect app, follow that instruction. The desktop app is the sign-in path on that workstation.
## Headless machines and CI
Set `ASPECT_API_KEY` through your job runner's secret or environment settings. Authenticated commands use it without a preceding `auth login`:
```bash theme={null}
# ASPECT_API_KEY is supplied by your job runner.
aspect auth status --json
aspect ls "aspect://Acme/Documentary" --json
```
On a machine without an active desktop session, the environment key overrides a stored key. Avoid embedding a real key in commands, checked-in scripts, logs, or prompts. `auth login` without a supplied key cannot prompt in `--json` mode; an environment key is the normal choice for scripts.
## Sign out or revoke a key
```bash theme={null}
aspect auth logout
```
This removes the CLI's stored key and clears its saved default workspace. It does **not** revoke that key in Aspect, remove `ASPECT_API_KEY` from your environment, or sign out the desktop app.
To revoke a key, delete it from **Settings → API Keys** in the web app. To change the desktop identity, sign out of the desktop app. Check `aspect auth status` after changing credentials so you know which identity the next command will use.
If a command reports `not_logged_in` or `invalid_api_key`, follow [Troubleshooting](/docs/cli/troubleshooting#authentication).
# Scripts and AI agents
Source: https://aspect.inc/docs/cli/automation
Use JSON output, background transfers, and the Aspect skill in scripts, CI, and AI tools
Use the Aspect CLI to move media between a computer and Aspect, retrieve proxies, and work with mounted projects. Every public command accepts `--json` for scripts and AI agents.
## Discover commands
```bash theme={null}
aspect --version --json
aspect --help --json
aspect download --help --json
```
Root help lists the public commands. Command help describes its usage, actions, settings, flags, environment variables, and examples. Read the installed CLI's help when generating a command; available options can change between versions.
The [command reference](/docs/cli/commands) documents the public interface.
## Authenticate without a prompt
On a headless machine or CI runner, configure `ASPECT_API_KEY` through your environment or secret manager. The key authenticates commands directly; there is no separate login step.
```bash theme={null}
# ASPECT_API_KEY is supplied by your job's secret manager.
aspect auth status --json
aspect ls "aspect://Studio/Production/Renders" --json
```
Keep keys out of command arguments, repository files, and logs. `aspect auth login` without a key argument is an interactive terminal flow; `--json` disables that prompt.
Authentication follows this order:
1. The Aspect desktop app, when it is running and signed in.
2. `ASPECT_API_KEY`.
3. A key saved by `aspect auth login`.
An environment key does not switch away from a signed-in desktop account. `aspect auth status --json` reports the source as `desktop`, `env`, or `auth-file`, and reports when a key is ignored. A signed-in desktop app that is offline also takes precedence; the CLI does not silently switch to a key.
See [authentication](/docs/cli/authentication) for creating keys and managing sign-in.
## Make destinations explicit
Include the workspace and project in each remote URL, and quote URLs or local paths that contain spaces:
```bash theme={null}
aspect upload ./final.mov "aspect://Studio/Client Campaign/Renders" --json
aspect download "aspect://Studio/Client Campaign/Footage" ./proxies --variant stream_proxy --json
```
`aspect://~/` depends on `ASPECT_WORKSPACE`, a saved default, or sole workspace membership. Explicit workspace URLs make a job independent of that local configuration. There is no `--workspace` flag. See [paths and workspaces](/docs/cli/paths).
Choose conflict behavior deliberately. Uploads and downloads skip existing filenames by default. Use `--replace` to replace them or `--keep-both` to preserve both copies. These two flags cannot be combined.
For viewing or analysis, [stream proxies](/docs/cli/proxies) can avoid downloading large originals. A directory download omits assets that do not have the selected variant, so check that you received the media your job needs.
## Parse JSON and exit codes
With `--json`:
* stdout contains the JSON result.
* Command errors go to stderr as a JSON error object.
* Interactive prompts and progress bars are disabled. Without `--json`, progress is written to stderr only when it is a terminal.
Keep stdout and stderr separate. Do not merge them with `2>&1` before parsing.
| Exit code | Meaning |
| - | - |
| `0` | Command completed successfully. For a detached launch, this means the background transfer was started. |
| `1` | Command failure, a failed check, or a transfer that failed or was cancelled. |
| `2` | Usage error, such as missing arguments, an invalid URL, or incompatible options. |
An error object has this shape:
```json theme={null}
{
"error": {
"code": "not_found",
"message": "The requested item could not be found."
}
}
```
Branch on `error.code`; display `error.message` to the person operating the job. Common codes include `usage`, `not_logged_in`, `invalid_api_key`, `not_found`, `ambiguous_name`, `api_request_failed`, `network_timeout`, `network_unreachable`, `daemon_error`, and `daemon_owned_by_desktop`.
Exit code `1` can include a normal JSON result on stdout. `doctor` returns its checks, `transfer status` and `transfer wait` return the transfer snapshot, and uploads or downloads with per-file failures return their summary. Check stdout before assuming stderr contains an error object.
For example, a foreground upload can return this summary and exit `1`:
```json theme={null}
{
"uploaded": 2,
"skipped": 0,
"failed": [
{
"path": "clip-03.mov",
"error": "Transfer failed"
}
]
}
```
Foreground downloads use `downloaded` instead of `uploaded`. Skipped files do not make a transfer fail. Treat the exit code as well as the result as significant, and allow additional JSON fields as the CLI evolves.
## Run a background transfer
Add `--detach` when a transfer should outlive the foreground CLI process:
```bash theme={null}
aspect download "aspect://Studio/Production/Footage" ./proxies --variant stream_proxy --detach --json
```
The launch result contains `id`:
```json theme={null}
{
"id": "6bc60177-a942-484a-a7f8-f624c1b617d7"
}
```
Pass that ID to the transfer commands:
```bash theme={null}
aspect transfer status 6bc60177-a942-484a-a7f8-f624c1b617d7 --json
aspect transfer wait 6bc60177-a942-484a-a7f8-f624c1b617d7 --json
```
`wait` blocks until a terminal state. Both commands return the snapshot directly, with fields including:
| Field | Meaning |
| - | - |
| `id` | Transfer ID. |
| `op` | `upload` or `download`. |
| `state` | `running`, `succeeded`, `failed`, or `cancelled`. |
| `filesDone`, `filesTotal` | File progress counts. |
| `bytesDone`, `bytesTotal` | Byte progress counts. |
| `progress` | Completion fraction from `0` to `1`. |
| `speedMbps`, `etaSeconds` | Current megabits per second and estimated seconds remaining. |
| `result` | Final summary: `succeeded`, `skipped`, `failed` entries, and an optional overall `error`. |
`aspect transfer list --json` wraps its snapshots in a `transfers` array. `aspect transfer cancel --json` requests cancellation; use `wait` to collect the terminal outcome.
The runner writes its first snapshot after launch. An immediate `status` or `wait` can briefly return `transfer_not_found`; retry that error briefly for a newly launched ID. Other failures need their own handling.
This Python example starts a proxy download, handles that short startup window, and preserves the final JSON and exit code. It requires Python 3 and `aspect` on `PATH`:
```python theme={null}
import json
import subprocess
import sys
import time
def finish(process):
sys.stdout.write(process.stdout)
sys.stderr.write(process.stderr)
raise SystemExit(process.returncode)
launch = subprocess.run(
[
"aspect", "download", "aspect://Studio/Production/Footage",
"./proxies", "--variant", "stream_proxy", "--detach", "--json",
],
capture_output=True,
text=True,
)
if launch.returncode != 0:
finish(launch)
transfer_id = json.loads(launch.stdout)["id"]
for attempt in range(20):
result = subprocess.run(
["aspect", "transfer", "wait", transfer_id, "--json"],
capture_output=True,
text=True,
)
if result.stdout or result.returncode != 1:
finish(result)
try:
code = json.loads(result.stderr).get("error", {}).get("code")
except json.JSONDecodeError:
finish(result)
if code != "transfer_not_found" or attempt == 19:
finish(result)
time.sleep(0.25)
```
Background transfers still depend on the machine staying awake and running. CI systems may terminate background processes when a job ends; wait for the result inside the job when completion matters. See [background transfers](/docs/cli/transfers).
## Connect AI agents
Install the official CLI skill:
```bash theme={null}
aspect skills add
```
This requires Node.js and `npx`. It installs the `aspect-cli` skill from `aspect-hq/aspect-cli` at user scope for supported agents detected on the machine. The skill teaches authentication, path handling, JSON results, transfers, mounts, and offline pins.
Use the CLI for local files, transfers, proxies, and mounts. Connect the [Aspect MCP server](/docs/api-reference/mcp) for searching and understanding media, transcripts, collections, metadata, comments, and sharing:
```text theme={null}
https://api.aspect.inc/mcp
```
For example, an agent can find relevant clips through MCP and retrieve their proxies through the CLI. Both use the permissions of the authenticated account; connecting MCP does not itself authenticate the local CLI.
See [Searching and filtering](/docs/cli/searching-and-filtering) for combining visual, transcript, document, and filename signals with metadata filters. Content search uses API/MCP calls alongside the CLI; there is no native CLI search command.
## Documentation for language models
* [CLI documentation index](https://aspect.inc/docs/cli/llms.txt): links to this section's guides and reference.
* [Site documentation index](https://aspect.inc/docs/llms.txt): links across the Aspect documentation.
* [Full documentation text](https://aspect.inc/docs/llms-full.txt): the site's documentation in a combined text format.
Use the documentation for workflows and concepts, and `aspect --help --json` for the options supported by the installed binary.
# Cache and offline files
Source: https://aspect.inc/docs/cli/cache-and-offline
Control local cache usage, pin complete files for offline access, and confirm synchronization before going offline.
Aspect keeps file content locally in two ways. The **cache** holds data fetched as you work and can evict it to free space. **Pins** keep selected files available locally for offline use through a mount.
Opening a file once does not guarantee that all of it is cached or will remain available offline. Pin the files you need and wait for synchronization.
## Prepare an offline session
```bash theme={null}
aspect mount "aspect://Acme/Documentary"
```
A new CLI mount resolves its path through Aspect's API. Create the mount while online rather than relying on a pin to make a later mount command work without a connection.
```bash theme={null}
aspect pin add "aspect://Acme/Documentary/Footage"
```
The target can be a project, directory, or individual asset. The command registers the pin; its return does not mean downloading has finished. Adding the same pin again returns the existing pin.
```bash theme={null}
aspect pin list
aspect pin list --json
```
Confirm that the needed pins show `synced`, and that their downloaded content is complete. Check errors or storage limits before leaving the network.
Work through the existing mount. [Check for pending or failed uploads](/docs/cli/mounts#finish-work-and-unmount) before disconnecting, and let Aspect synchronize changes after reconnecting.
## Pin states
| State | Meaning and next step |
| - | - |
| `fetching_metadata` | Aspect is finding the files included in the pin. Wait. |
| `downloading_chunks` | Content is still downloading. Keep the computer online. |
| `synced` | The pin has synchronized. |
| `error` | Synchronization failed. Inspect the reported error and your connection. |
| `over_limit` | The pin exceeds available pin storage. Remove unneeded pins or increase the limit. |
`aspect status` also includes an overall pin sync summary. For an offline session, inspect the specific pins you need rather than relying only on an aggregate byte count.
## Set storage limits
```bash theme={null}
aspect settings list
aspect settings set cache-limit 200GB
aspect settings set pin-limit 500GB
```
These settings apply to Aspect on this computer, including the shared filesystem service when you use the desktop app.
| Setting | Controls | Minimum |
| - | - | - |
| `cache-limit` | Storage for content cached as you open it | `10GB` |
| `pin-limit` | Storage for pinned offline content | `5GB`, and not below content already pinned |
Sizes require a unit: `B`, `KB`, `MB`, `GB`, or `TB`. They are decimal units; fractional sizes such as `1.5TB` are accepted. `aspect settings list --json` reports values in bytes. Choose limits that leave room for your other files and applications.
## Remove a pin
```bash theme={null}
aspect pin remove "aspect://Acme/Documentary/Footage"
```
You can also pass a pin ID from `aspect pin list --json`.
Removing a pin removes the offline-retention requirement. It does not delete files from Aspect, and cached content may remain on disk until the cache evicts it.
A file included only through a pinned parent folder does not have its own pin to remove. If `pin remove` reports `not_pinned` for that file, remove the parent's pin instead. Pin smaller folders or individual assets when you need finer control.
For a local copy that you manage independently of mounted-drive caching, use [download](/docs/cli/downloads).
# Command reference
Source: https://aspect.inc/docs/cli/commands
Every public Aspect CLI command, action, and option
The `aspect` CLI uploads and downloads media, lists your library, mounts projects, and manages local transfers and storage. See [installation](/docs/cli/installation) to get the CLI and [authentication](/docs/cli/authentication) to connect your account.
## Help and global options
```bash theme={null}
aspect --help
aspect download --help
aspect --version
aspect download --help --json
```
| Option | Behavior |
| - | - |
| `--help` | Show help for the CLI or a command. `aspect help download` is equivalent to `aspect download --help`. |
| `-h` | Short form for root help or a command's leading help argument, such as `aspect download -h`. |
| `--version` | Print the version with `aspect --version`. |
| `--json` | Return machine-readable output and disable interactive prompts. Available on every public command. |
Running a command group, such as `aspect transfer`, without an action shows its help. Use `--help --json` to discover the actions and options in your installed version. See [scripts and AI agents](/docs/cli/automation) for output formats and exit codes.
## Authentication
```bash theme={null}
aspect auth login
aspect auth status
aspect auth logout
```
| Action | Behavior |
| - | - |
| `login` | Validate an API key and save it for later commands. In an interactive terminal, prompts for the key without displaying it. |
| `status` | Report the active authentication source: `desktop`, `env`, or `auth-file`, or explain why no credential is available. |
| `logout` | Remove the saved API key. Does not sign out the desktop app or unset environment variables. |
`auth login` accepts `--api-key `. Prefer the interactive prompt for people and `ASPECT_API_KEY` for automation, so keys stay out of command arguments and shell history.
When the Aspect desktop app is running and signed in, its account takes precedence over API keys. Otherwise, `ASPECT_API_KEY` takes precedence over the saved key. Read [authentication](/docs/cli/authentication) for setup and account switching.
## Browse workspaces and files
### `ls`
```bash theme={null}
aspect ls
aspect ls "aspect://Studio/"
aspect ls "aspect://Studio/Production/Renders"
```
| Target | Result |
| - | - |
| No argument, or `aspect://` | Your workspaces. |
| `aspect:///` | Projects in that workspace. |
| A project or directory | Its immediate child directories and assets. |
| A single asset | That asset's entry. |
With `--json`, the result is an array of entries with `id`, `name`, and `type`. A returned entry may also include `size` in bytes or `updatedAt` when available.
### `workspace`
```bash theme={null}
aspect workspace list
aspect workspace use "Studio"
```
| Action | Behavior |
| - | - |
| `list` | List available workspaces and identify the default. |
| `use ` | Save a default workspace by name or ID for `aspect://~/` URLs. |
`ASPECT_WORKSPACE` overrides the saved default for `~`. Explicit workspace URLs are useful in scripts because they do not depend on that default. See [paths and workspaces](/docs/cli/paths).
## Upload
```bash theme={null}
aspect upload ... "aspect:///[/]"
```
Provide one or more local files or directories, followed by the remote destination. Directories are uploaded recursively. Existing names are skipped by default.
| Option | Behavior |
| - | - |
| `--replace` | Replace existing files with the same name. |
| `--keep-both` | Keep both copies when names conflict. Cannot be combined with `--replace`. |
| `--detach` | Start a background transfer and return its ID. |
```bash theme={null}
aspect upload ./final.mov ./thumbnail.jpg "aspect://Studio/Production/Renders"
aspect upload ./Footage "aspect://Studio/Production" --keep-both --detach
```
See [uploads](/docs/cli/uploads) for destination behavior and conflict handling, and [background transfers](/docs/cli/transfers) for tracking a detached upload.
## Download
```bash theme={null}
aspect download "aspect:///[/]" []
```
Download one asset, a directory, or a project. The local destination defaults to the current directory. Existing local filenames are skipped by default.
| Option | Behavior |
| - | - |
| `--variant ` | Select `original` (default), `stream_proxy`, or `preview`. |
| `--replace` | Replace existing local files with the same name. |
| `--keep-both` | Keep both local copies by adding a numeric suffix. Cannot be combined with `--replace`. |
| `--detach` | Start a background transfer and return its ID. |
```bash theme={null}
aspect download "aspect://Studio/Production/Renders/final.mov" ./downloads
aspect download "aspect://Studio/Production/Footage" ./proxies --variant stream_proxy
aspect download "aspect://Studio/Production" ./backup --detach
```
`stream_proxy` retrieves the H.264 MP4 proxy, up to 1080p, with AAC audio when the source has audio. `preview` retrieves the preview image. A directory or project download leaves out assets without the requested variant; selecting a single asset without that variant fails.
See [downloads](/docs/cli/downloads) for local folder behavior and [proxies and previews](/docs/cli/proxies) for variant availability and filenames.
## Background transfers
```bash theme={null}
aspect transfer list
aspect transfer status
aspect transfer wait
aspect transfer cancel
```
| Action | Behavior |
| - | - |
| `list` | List detached transfers recorded on this computer. |
| `status ` | Show one transfer's current progress and outcome. |
| `wait ` | Block until a transfer finishes, then return its final result. |
| `cancel ` | Request cancellation of a running transfer. |
IDs come from `upload --detach` or `download --detach`. These commands track detached CLI transfers, not every transfer in your workspace. A failed or cancelled transfer makes `status` and `wait` exit with code `1` while still returning its snapshot on stdout.
See [background transfers](/docs/cli/transfers) for result fields and cancellation behavior.
## Mounts
### `mount`
```bash theme={null}
aspect mount "aspect://Studio/Production"
aspect mount "aspect://Studio/Production/Renders" --name Renders
```
Mount a project or directory as a local volume. `--name ` sets the volume's display name; the default is the project or directory name. Mounting a single asset is not supported.
### `unmount`
```bash theme={null}
aspect unmount Renders
aspect unmount "aspect://Studio/Production"
```
Unmount by volume name or the same Aspect URL used to mount it. See [mounts](/docs/cli/mounts) for platform prerequisites, local access, and writes.
## Offline pins and storage settings
### `pin`
```bash theme={null}
aspect pin list
aspect pin add "aspect://Studio/Production/Footage"
aspect pin remove "aspect://Studio/Production/Footage"
```
| Action | Behavior |
| - | - |
| `list` | Show pins, sync status, and synced and total bytes. |
| `add ` | Pin a project, directory, or asset for offline access through a mount. |
| `remove ` | Remove a pin by URL or the ID returned by `pin list --json`. |
Adding an existing pin returns that pin. If a file is available because a parent directory is pinned, remove the parent pin to unpin it. Wait for synchronization to complete before relying on a pin offline.
### `settings`
```bash theme={null}
aspect settings list
aspect settings set cache-limit 200GB
aspect settings set pin-limit 1.5TB
```
| Setting | Behavior |
| - | - |
| `cache-limit` | Limit local storage for automatically cached content. Minimum: `10GB`. |
| `pin-limit` | Limit local storage for pinned content. Minimum: `5GB`; cannot be lower than the content already pinned. |
`settings list` reports the current settings. `settings set ` changes one. Sizes require a unit: `B`, `KB`, `MB`, `GB`, or `TB`. Units are decimal, and fractional values such as `1.5TB` are accepted. Settings persist on this computer and apply to its filesystem service.
See [cache and offline access](/docs/cli/cache-and-offline) for the difference between cached content and complete pins.
## Status and diagnostics
### `status`
```bash theme={null}
aspect status
```
Show authentication, the filesystem service, mounted volumes, an overall pin summary, and transfers together.
### `doctor`
```bash theme={null}
aspect doctor --json
```
Check authentication, the CLI installation, the filesystem service, and the operating system's mount prerequisites. `doctor` reports issues and suggested fixes; it does not install or repair prerequisites. A failing check returns exit code `1` with the checks on stdout.
### `daemon`
```bash theme={null}
aspect daemon status
aspect daemon start
aspect daemon stop
aspect daemon restart
```
| Action | Behavior |
| - | - |
| `status` | Show service state, version, mounts, and remaining write-back bytes per mount. |
| `start` | Start the service if needed. |
| `stop` | Stop the service. Remembered mounts return the next time it starts. |
| `restart` | Stop and start the service, picking up a newly installed version. |
The filesystem service starts automatically when a command needs it. Use these controls when troubleshooting. When the desktop app is signed in and owns the service, `start`, `stop`, and `restart` return `daemon_owned_by_desktop`; manage the service through the desktop app instead.
See [troubleshooting](/docs/cli/troubleshooting) for authentication, mount, and transfer errors.
## Updates and agent setup
### `upgrade`
```bash theme={null}
aspect upgrade
```
Install the latest CLI release. `--allow-downgrade` allows installing that release even if its version is older than the installed version. If the desktop app owns the filesystem service, the upgrade leaves restarting that service to the app.
### `skills add`
```bash theme={null}
aspect skills add
```
Install the official `aspect-cli` skill for supported AI agents detected on this computer. This command requires Node.js and `npx` and installs at user scope. See [scripts and AI agents](/docs/cli/automation).
## Environment variables
| Variable | Behavior |
| - | - |
| `ASPECT_API_KEY` | API key for headless use. Overrides the saved key; a signed-in desktop app takes precedence over both. |
| `ASPECT_AUTH_FILE` | Override the saved API-key file path. Default: `~/.aspect/cli/auth.json`. |
| `ASPECT_WORKSPACE` | Default workspace name or ID for `aspect://~/` URLs. Overrides the saved workspace default. |
# Download files
Source: https://aspect.inc/docs/cli/downloads
Download original media, directories, and projects to your computer, with explicit conflict handling and completion results.
Use `aspect download` to save an ordinary local copy of an asset:
```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./downloads
```
The optional final argument is a **local directory**, not a new filename. It defaults to your current directory. The CLI creates needed local directories and uses the asset's filename.
## Download a folder or project
```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage" ./downloads
aspect download "aspect://Acme/Documentary" ./delivery
```
Folder downloads preserve the directory tree under the selected folder's name. For example, downloading `Footage` to `./downloads` puts its files under `./downloads/Footage/`. The completion message, or the JSON result's `path`, reports the local destination.
These are copies. Changes to downloaded files do not automatically synchronize with Aspect. Use [upload](/docs/cli/uploads) to send a revision back, or [mount the project](/docs/cli/mounts) for a live filesystem workflow.
## Originals, proxies, and previews
The default variant is `original`. Select another representation with `--variant`:
```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./downloads --variant original
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./proxies --variant stream_proxy
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./previews --variant preview
```
See [Retrieve proxies and previews](/docs/cli/proxies) for filenames and how missing variants are handled.
## Existing local files
| Option | Behavior |
| - | - |
| No conflict flag | Leave an existing local file in place and skip it. |
| `--replace` | Download a replacement for the existing local file. |
| `--keep-both` | Save another copy with a numeric suffix. |
```bash theme={null}
aspect download "aspect://Acme/Documentary/Deliverables" ./delivery --replace
```
Skipping an existing path does not verify that its contents match the remote file. Use `--replace` when you need to refresh an existing copy. Do not combine the two conflict flags.
## Completion and interruptions
Downloads write to temporary `.part` files and move them into place when complete. Cancelling a running download removes its in-flight temporary files; a completed filename is not left pointing to a partially downloaded file.
Rerunning a download skips existing final files by default. It retries the missing files as a new download rather than continuing a partial file from its previous offset.
For a large delivery, run in the background:
```bash theme={null}
aspect download "aspect://Acme/Documentary/Deliverables" ./delivery --detach
```
Then use [transfer status or wait](/docs/cli/transfers) to confirm completion. With `--json`, the final result contains `downloaded`, `skipped`, `failed`, and the destination `path`. A directory with no files matching the requested variant can complete with zero downloads, so inspect the count if your workflow expects media.
# Aspect CLI
Source: https://aspect.inc/docs/cli/index
Upload and download media, retrieve proxies, mount projects, and automate file workflows from your terminal on macOS, Windows, and Linux.
The `aspect` command connects the files on your computer to your Aspect workspace. Use it to upload a shoot, download a delivery, retrieve smaller video proxies, or mount a project so your applications can open its files directly.
The CLI runs on **macOS, Windows, and Linux**. It comes included with the [Aspect desktop app for macOS and Windows](https://aspect.inc/download), and can also be installed independently on machines such as Linux workstations and servers.
## Get started
**macOS and Windows:** [Download the Aspect desktop app](https://aspect.inc/download). Install and open it to get the included CLI, then open a new terminal.
**Linux or a standalone CLI installation:** use the installer for your operating system:
```bash macOS / Linux theme={null}
curl -fsSL https://aspect.inc/cli/install.sh | sh
```
```powershell Windows theme={null}
powershell -ExecutionPolicy Bypass -c "irm https://aspect.inc/cli/install.ps1 | iex"
```
Open a new terminal after installation, then run `aspect --version`.
If the Aspect desktop app is running and signed in, the CLI uses that account automatically. Check it with:
```bash theme={null}
aspect auth status
```
On a machine without the desktop app, create an API key in Aspect's **Settings → API Keys** and use `aspect auth login` to enter it interactively. For a server or CI job, provide the key through `ASPECT_API_KEY`. See [Authentication](/docs/cli/authentication).
```bash theme={null}
aspect ls
aspect ls "aspect://Acme/"
aspect ls "aspect://Acme/Documentary/"
```
Replace `Acme` and `Documentary` with your workspace and project names. [Aspect paths](/docs/cli/paths) also accept IDs.
```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./downloads
```
To get its streaming proxy instead, add `--variant stream_proxy`.
## Choose a workflow
| You want to… | Start here |
| - | - |
| Send files or folders from your computer to Aspect | [Upload files](/docs/cli/uploads) |
| Save originals or a folder tree to a local disk | [Download files](/docs/cli/downloads) |
| Get smaller video files or poster images | [Retrieve proxies and previews](/docs/cli/proxies) |
| Find media by its content and combine search signals with filters | [Searching and filtering](/docs/cli/searching-and-filtering) |
| Open cloud media from editing applications or filesystem tools | [Mount projects](/docs/cli/mounts) |
| Keep media available for an offline session | [Cache and offline files](/docs/cli/cache-and-offline) |
| Run a transfer after closing your terminal | [Background transfers](/docs/cli/transfers) |
| Build a script or give a coding agent access to media | [Scripts and AI agents](/docs/cli/automation) |
| Look up a command or resolve an error | [Command reference](/docs/cli/commands) · [Troubleshooting](/docs/cli/troubleshooting) |
Content search combines the CLI with the [Aspect MCP server](/docs/api-reference/mcp) or [REST API](/docs/api-reference/index); the current CLI has no native search command. MCP and REST also cover metadata, collections, and review workflows.
Giving these docs to an AI tool? Start with the [CLI documentation index](https://aspect.inc/docs/cli/llms.txt). Mintlify also provides an [index of all Aspect docs](https://aspect.inc/docs/llms.txt) and the [full documentation text](https://aspect.inc/docs/llms-full.txt).
# Installation and updates
Source: https://aspect.inc/docs/cli/installation
Install the Aspect CLI on macOS, Windows, or Linux, check mount prerequisites, and update an existing installation.
The CLI comes included with the **Aspect desktop app for macOS and Windows**. You can also install it separately on macOS, Windows, or Linux. You do not need to install Node.js, Bun, or Python to use it.
## Supported platforms
| Operating system | Release builds | Mounting prerequisite |
| - | - | - |
| macOS | Apple silicon and Intel | Aspect's bundled mount helper; the first mount may request administrator approval |
| Windows | x86-64 | WinFSP |
| Linux | x86-64 and ARM64 | FUSE 3, including `fusermount3` |
Mount prerequisites apply to `aspect mount`. Uploading, downloading, listing files, and retrieving proxies do not require a mounted drive.
## Install
### With the desktop app on macOS or Windows
[Download Aspect at aspect.inc/download](https://aspect.inc/download), install the version for your operating system, and open the app. The desktop app includes the CLI, so a separate CLI installation is not needed.
Open a new terminal and run `aspect --version` to check it. When the desktop app is running and signed in, the CLI uses the same account automatically.
### Standalone CLI
Use these installers for Linux, headless machines, or a CLI installation without the desktop app:
```bash theme={null}
curl -fsSL https://aspect.inc/cli/install.sh | sh
```
The installer detects your operating system and processor, downloads the matching release, checks its SHA-256, and installs it under `~/.aspect/bin`. It adds that directory to your shell's path when needed.
Open a new terminal, or apply the `PATH` command printed by the installer.
Run in PowerShell:
```powershell theme={null}
powershell -ExecutionPolicy Bypass -c "irm https://aspect.inc/cli/install.ps1 | iex"
```
The installer places the CLI under `%USERPROFILE%\.aspect\bin` and configures access from your terminal. Open a new terminal after installation.
You can inspect or download the release files directly from [GitHub Releases](https://github.com/aspect-hq/aspect-cli/releases/latest). Keep the release payload together: the mount adapter and helpers accompany the `aspect` executable.
## Verify the installation
```bash theme={null}
aspect --version
aspect --help
aspect doctor
```
`doctor` reports local prerequisites and suggested fixes. A mount prerequisite warning does not mean that file transfers are unavailable.
### Linux mounting
Install FUSE 3 with your distribution's package manager. For Debian or Ubuntu:
```bash theme={null}
sudo apt-get update
sudo apt-get install fuse3
```
Fedora uses `sudo dnf install fuse3`; Arch Linux uses `sudo pacman -S fuse3`. The installer tries to install FUSE 3 when it runs as root. Otherwise it prints guidance if FUSE is missing.
An interactive `aspect mount` can offer to install a missing prerequisite. Commands using `--json` do not prompt to install packages. Provision FUSE before running automated mount jobs.
### Windows and macOS mounting
On Windows, install [WinFSP](https://winfsp.dev/) if `aspect doctor` reports it missing. On macOS, the release includes Aspect's mount helper; a mount may request permission to install or update it. Follow the diagnostic message if the helper is missing.
## Update
```bash theme={null}
aspect upgrade
aspect --version
```
`upgrade` installs the latest published CLI release. When the CLI manages the filesystem service, an upgrade can restart it; finish work with mounted files before updating.
If the signed-in desktop app owns the service, the CLI installs the update and leaves that service running. Restart the Aspect app when instructed to update the service it runs.
Next, [sign in](/docs/cli/authentication) and [find a project](/docs/cli/paths).
# Mount projects
Source: https://aspect.inc/docs/cli/mounts
Mount an Aspect project or folder, open files on demand, save changes, and check background uploads before unmounting.
A mount makes an Aspect project available as a local volume. Editing applications, file managers, and command-line tools can open files through that volume while Aspect retrieves data on demand.
Mounting requires access to the project and your operating system's [mounting prerequisites](/docs/cli/installation#supported-platforms).
## Mount a project or folder
```bash theme={null}
aspect mount "aspect://Acme/Documentary"
```
To mount only one folder and give the volume a clear name:
```bash theme={null}
aspect mount "aspect://Acme/Documentary/Footage" --name Documentary-Footage
```
The result reports the volume name, mount point, and status. `aspect mount --json` includes `name`, `mountPoint`, and `status`; use the actual mount point returned on your operating system rather than assuming a fixed location.
You can mount a project or directory. A workspace or individual file cannot be mounted. `--name` names the volume; it is not a custom filesystem path.
## Open and edit files
Open the returned mount point in Finder, File Explorer, or your Linux file manager, or select it in an application's file picker. File reads use local cached data when available and retrieve missing content from Aspect. A mount therefore uses local disk space as you work, without requiring a complete project download first.
When you have permission to write, save files into the volume as you would on another drive. You can also rename or move files within the mounted volume using your file manager or normal filesystem tools. These changes affect the project in Aspect.
Writes first land locally and are uploaded in the background after the application's writable file handles close. A completed save dialog is not a confirmation that the file is already uploaded. Other people's changes can arrive through the mounted project too; coordinate edits to the same file because simultaneous writes are not automatically merged.
For independent local copies, use [download](/docs/cli/downloads). For a large explicit upload with a transfer ID, use [upload](/docs/cli/uploads).
## Check the mount
```bash theme={null}
aspect status
aspect daemon status
```
`status` provides an overview of the filesystem service, mounts, pin synchronization, and CLI transfers. Use [Troubleshooting](/docs/cli/troubleshooting) if a mount remains in a starting or error state.
## Finish work and unmount
1. Close files or applications that are writing into the volume.
2. Run `aspect daemon status --json`. Check that `writeBackDrained` is `true` **and** `writeSyncSummary.failureCount` is `0`, with no mount errors. A drained queue alone does not rule out failed uploads. If these fields are missing, upload completion is unknown; keep Aspect running and investigate before disconnecting or shutting down.
3. Unmount by volume name or Aspect URL:
```bash theme={null}
aspect unmount Documentary-Footage
```
```bash theme={null}
aspect unmount "aspect://Acme/Documentary/Footage"
```
`aspect transfer wait` waits for a detached CLI transfer, not the writes made by applications through this mount. A shell `sync` command is also not a confirmation that cloud uploads have completed.
## The background service
The filesystem service keeps a mount available after the `mount` command exits. With a signed-in desktop app, the app owns that service. With a standalone CLI installation, commands start it when needed.
The service remembers mounts and restores them when it next starts for the same account. Explicitly unmounting removes that remembered mount. This does not install a Linux service that starts automatically at login; the CLI has no `daemon install` command.
When the desktop app owns the service, manage it through the app. `aspect daemon start`, `stop`, and `restart` return `daemon_owned_by_desktop` in that state.
For offline preparation, [pin files while online](/docs/cli/cache-and-offline) and keep the mount available before disconnecting.
# Paths and core concepts
Source: https://aspect.inc/docs/cli/paths
Address workspaces, projects, directories, and assets with aspect:// URLs, use IDs, and choose a default workspace.
Aspect paths follow the same hierarchy you see in the app:
```text theme={null}
aspect://///
```
A **workspace** holds your team's projects. A **project** holds folders and assets. A **directory** is a folder, and an **asset** is a file. A project is also the boundary for a mounted volume; you can mount its root or a folder within it.
## Browse from the top
```bash theme={null}
aspect ls
aspect ls "aspect://Acme/"
aspect ls "aspect://Acme/Documentary/"
aspect ls "aspect://Acme/Documentary/Footage/"
aspect ls "aspect://Acme/Documentary/Footage/interview.mov"
```
These commands list workspaces, projects, a project's contents, a folder's contents, and one file respectively. `ls` lists one level at a time. Add `--json` to get entries with their IDs and types.
| Path | Refers to |
| - | - |
| `aspect://` | All workspaces you can access |
| `aspect://Acme` | The Acme workspace |
| `aspect://Acme/Documentary` | A project |
| `aspect://Acme/Documentary/Footage` | A folder in that project |
| `aspect://Acme/Documentary/Footage/interview.mov` | One asset |
## Names, spaces, and IDs
Names are matched case-insensitively within their parent. Quote the whole URL so spaces and shell characters remain part of the path:
```bash theme={null}
aspect ls "aspect://Acme Post/Brand Film/Day 01"
```
Each segment can also be the resource's UUID. If a name matches more than one resource, the CLI returns `ambiguous_name` and candidate IDs. Replace the ambiguous segment with its ID; obtain IDs from `aspect ls --json` or `aspect workspace list --json`.
URL-encoded segments are accepted. A slash that is part of a name must be encoded as `%2F`, because an ordinary `/` separates path levels. An Aspect web or share link is not an `aspect://` path.
## Set a default workspace
```bash theme={null}
aspect workspace list
aspect workspace use "Acme"
aspect ls "aspect://~/Documentary"
```
`workspace use` saves a default on this computer. The `~` in the **workspace position** resolves in this order:
1. The `ASPECT_WORKSPACE` environment variable, if set to a workspace name or ID.
2. Your saved default workspace, if it is still accessible.
3. Your only workspace, if you belong to exactly one.
If no default can be selected, the CLI asks you to name a workspace. Explicit workspace URLs are useful in scripts because they do not depend on saved defaults.
## Mounts, downloads, and pins
| Operation | What you get |
| - | - |
| [Mount](/docs/cli/mounts) | A volume backed by your Aspect project. Applications fetch file data as they read it, and writes are uploaded in the background. |
| [Download](/docs/cli/downloads) | An ordinary local copy. Later edits to that copy are not automatically uploaded. |
| [Pin](/docs/cli/cache-and-offline) | Files kept locally for offline access through a mount. Wait for pin synchronization before disconnecting. |
| [Retrieve a proxy](/docs/cli/proxies) | A generated viewing copy, downloaded separately from the original. |
Collections curate files without changing their underlying project paths. Use the app or [MCP server](/docs/api-reference/mcp) to work with collections, then address files by their project and folder paths in the CLI.
Commands use the permissions of the signed-in account or API key owner. Knowing a path or an ID does not grant access to it.
# Retrieve proxies and previews
Source: https://aspect.inc/docs/cli/proxies
Download generated H.264 video proxies and poster images for review, analysis, or automation without downloading the original media.
Use `--variant` to choose the representation to download. This is useful when an original camera file is much larger than the viewing copy needed for review or analysis.
| Variant | What is downloaded | Example local filename |
| - | - | - |
| `original` | The original asset; the default | `interview.mov` |
| `stream_proxy` | The generated H.264 MP4 streaming proxy | `interview_proxy.mp4` |
| `preview` | A poster image, preferring a custom thumbnail when one exists | `interview_preview.webp` for a generated preview |
## Download one proxy
```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./proxies --variant stream_proxy
```
Streaming proxies are H.264 MP4 files with AAC audio when the source contains audio. They preserve aspect ratio, fit within a 1080p landscape or portrait frame, and are not upscaled. The CLI does not offer a resolution, bitrate, or codec selector.
These proxies are viewing copies. Use `original` when you need the source media's original quality and format for finishing or delivery. Downloading a proxy does not change the original in Aspect.
## Download a folder of proxies
```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage" ./proxies --variant stream_proxy
```
The command preserves the folder tree and gives each downloaded video a `_proxy.mp4` filename. It can also take a project URL.
For a background job:
```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage" ./proxies --variant stream_proxy --detach
```
Track the returned ID with [transfer commands](/docs/cli/transfers). Standard `--replace` and `--keep-both` [download options](/docs/cli/downloads#existing-local-files) apply to the resulting proxy filenames.
## Download preview images
```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./previews --variant preview
```
Generated poster images use WebP. If the asset has a custom thumbnail, the CLI prefers it and uses its format's extension, so a preview filename may instead end in `.jpg` or `.png`. Use the returned `path` rather than assuming the extension in a script.
## When a variant is missing
Proxy and preview files are produced by media processing. Upload completion does not guarantee that a requested variant already exists, and some assets do not have that representation.
| Request | Missing-variant behavior |
| - | - |
| One specific asset | The download fails if that asset lacks the requested variant. |
| A folder or project | Assets without the variant are left out. The download can succeed with zero files if none match. |
The download does not generate a missing proxy, wait for processing, or fall back to downloading originals. Check the asset in Aspect and retry after processing is complete. In automation, inspect the `downloaded` count and `failed` array; the number of proxy files can be smaller than the number of source assets.
## Retrieve a download URL through the API
If another application needs the proxy's URL, the REST API also exposes it:
```bash theme={null}
curl --fail --silent --show-error \
-H "Authorization: Bearer $ASPECT_API_KEY" \
"https://api.aspect.inc/assets//download?variant=stream_proxy"
```
Replace `` with the asset's `id` returned by:
```bash theme={null}
aspect ls "aspect://Acme/Documentary/Footage/interview.mov" --json
```
The response to the download-URL request includes `url` and `url_expires_at`. Fetch the returned URL before it expires; request another URL when needed rather than treating it as a permanent public link. The API checks the user's download permission.
For a preview that follows the CLI's custom-thumbnail preference, use `variant=preview&prefer_custom_thumbnail=true`. See the [API overview](/docs/api-reference/index) for authentication.
To work with proxies as local files, download them as shown above. `aspect mount` mounts the project filesystem and has no proxy-variant selector.
# Searching and filtering
Source: https://aspect.inc/docs/cli/searching-and-filtering
Find files by name, search visual content and spoken words, and combine metadata filters with ranked search through Aspect's API or MCP server.
Use the CLI to browse project paths and retrieve files. Use Aspect's API or [MCP server](/docs/api-reference/mcp) to search indexed content and metadata. **CLI v0.1.15 does not have a native `search` command.** The examples below distinguish terminal filtering of `aspect ls` output from content search requests.
## Filter a directory listing
`aspect ls` lists one level. Its JSON entries include `id`, `name`, and `type`; asset entries can also include `size` in bytes.
With [jq](https://jqlang.org/) installed, find filenames containing a word:
```bash theme={null}
aspect ls "aspect://Acme/Documentary/Footage" --json |
jq '[.[] | select(.type == "asset" and (.name | ascii_downcase | contains("interview")))]'
```
Or select files at least 1 GB in size:
```bash theme={null}
aspect ls "aspect://Acme/Documentary/Footage" --json |
jq '[.[] | select(.type == "asset" and (.size // 0) >= 1000000000)]'
```
These filters run locally on the returned listing. They do not inspect transcripts, search nested folders, or perform semantic matching. Browse a child folder explicitly, or use project search below.
## Choose a content channel
Search requests contain one or more **signals**. Each signal names a channel and the text to match:
| Channel | Searches | Example query |
| - | - | - |
| `visual` | Visible scenes, objects, actions, settings, and appearance | `person holding a camera outdoors` |
| `transcript` | Spoken words, dialogue, and narration, using text and semantic matching | `discussing the production budget` |
| `document` | Written text inside indexed document pages | `payment terms` |
| `filename` | Asset names, including ranked exact, prefix, substring, and fuzzy matches | `interview_final` |
Use short, direct descriptions. Transcript search concerns speech; a query for `applause` is not an audio-event detector. Filename search does not search folder paths and is not a glob or regular expression. For a strict filename condition, use the **Name** metadata filter described below.
Content channels depend on the asset's available processing results. A recently uploaded file may have a name before its transcript or visual analysis is ready.
## Run a search from the terminal
First find your project ID. This returns the projects in a workspace:
```bash theme={null}
aspect ls "aspect://Acme" --json
```
Set `PROJECT_ID` to the selected project's UUID, and configure `ASPECT_API_KEY` as described in [Authentication](/docs/cli/authentication). Raw `curl` requests use that key directly, independently of whichever desktop account the CLI uses.
```bash theme={null}
PROJECT_ID="your-project-uuid"
jq -n --arg project_id "$PROJECT_ID" '{
project_id: $project_id,
spec: {
signals: [
{id: "visual-1", signal: "visual", query: "person holding a camera outdoors"}
],
filters: []
}
}' > request.json
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $ASPECT_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @request.json \
https://api.aspect.inc/search/run > results.json
jq '.assets[] | {id, name, score: .search.score, matches: .search.moments}' results.json
```
This is a complete request. The following recipes show only its `spec` value unless stated otherwise. Keep `project_id` at the top level when sending them.
### Combine visual and spoken content
```json theme={null}
{
"signals": [
{"id": "visual-1", "signal": "visual", "query": "person holding a camera", "weight": 0.7},
{"id": "transcript-1", "signal": "transcript", "query": "production budget", "weight": 0.3}
],
"filters": []
}
```
Signals contribute to **ranking**. Combining them does not require every returned asset to match every signal. The weights give visual matching more influence in this example; they are not minimum confidence thresholds or percentages of required matches. Omit weights for equal relative importance, and omit a channel when you do not need it.
Matching happens at the asset level. A visual match and a spoken match can occur at different times in the same video. Inspect their individual moments before assuming that someone says a phrase while the requested action is on screen. Use metadata filters for mandatory constraints.
## Discover metadata filters
Filters refer to attribute UUIDs. Select fields also use **option UUIDs**, rather than their displayed labels. Retrieve the available attributes for your project:
```bash theme={null}
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $ASPECT_API_KEY" \
"https://api.aspect.inc/metadata/attributes?project_id=$PROJECT_ID" > attributes.json
jq '.[] | select(.is_filterable) | {id, name, data_type, options}' attributes.json
```
The response is an array. For example, discover the Type attribute and its options:
```bash theme={null}
jq '.[] | select(.name == "Type") | {id, options}' attributes.json
```
Use the returned attribute ID and the option ID labeled Video in a Type filter. Discover custom fields in the same way; do not reuse another project's custom attribute IDs.
With MCP, call `assets_search_capabilities` with `project_id` to obtain channel descriptions, filter attributes, valid clauses, and selectable values. Its `select_options` field supplies option IDs. The current capabilities response omits **Path**; use the REST attribute list to discover Path for folder filters.
### Apply mandatory conditions
This `spec` selects videos with a duration from 30 through 120 seconds. Replace every placeholder with a discovered UUID:
```json theme={null}
{
"signals": [],
"filters": [
{"id": "type-attribute-uuid", "clause": "eq", "values": ["video-option-uuid"]},
{"id": "duration-attribute-uuid", "clause": "gte", "values": [30]},
{"id": "duration-attribute-uuid", "clause": "lte", "values": [120]}
]
}
```
An empty `signals` array makes this a **filter-only search**. At least one signal or filter is required. Add these filters to a visual or transcript search to keep only ranked candidates that satisfy them.
Separate filter entries combine with **AND**. Multiple values inside a positive `eq`, `contains`, or `includes` filter match **any** listed value. For example, one Name `contains` filter with `["interview", "b-roll"]` matches either string. Two separate Name filters require both. For ranges, use separate lower and upper bounds as above.
| Attribute kind | Useful clauses |
| - | - |
| Name or other text | `eq`, `neq`, `contains`, `not_contains`, `starts_with`, `ends_with` |
| Duration, size, or another number | `eq`, `neq`, `gt`, `gte`, `lt`, `lte` |
| Multi-select, uploaded-by user, or People | `includes`, `not_includes` |
| Boolean | `is_true`, `is_false` |
Use the clauses valid for the selected attribute. Text comparisons are case-insensitive; `%` and `_` are literal characters. `includes` matches any selected value, while `not_includes` excludes the listed values. Boolean clauses and supported `exists`/`not_exists` checks need no comparison values.
### Search within a folder
Discover the **Path** attribute's ID from `attributes.json` and the folder's ID by listing its parent with `aspect ls --json`. Add this filter to `spec.filters`:
```json theme={null}
{"id": "path-attribute-uuid", "clause": "includes", "values": ["folder-uuid"]}
```
`includes` covers the folder and all nested folders. Use `eq` to restrict results to immediate children. A list of folder UUIDs matches any listed location. The request still needs the containing project's `project_id`.
### Find a known person
Use the **People** attribute and a known FACE entity UUID. MCP capabilities can provide available person options; `entities_list` can also discover entity IDs. Putting someone's name in a visual query is not equivalent to filtering for their recognized identity.
```json theme={null}
{"id": "people-attribute-uuid", "clause": "includes", "values": ["person-entity-uuid"]}
```
One People filter listing two people matches either person. To require both, add two filters, each containing one person's UUID. Both people may appear at different times. Recognition depends on processed face tracks and the identities available to the project.
## Read results and narrow the search
REST results are in `assets`; each asset's `search` contains an ordering `score`, a `confidence` label, signal summaries, and `moments`. A score is not a probability. Filter-only results use score `1` and confidence `unknown`.
Moments can include `start_time` and `end_time` in seconds, a 1-indexed document `page`, and an `evidence_text` excerpt marked `lexical` or `semantic`. Filename matches are asset-level and need not have timestamps. Excerpts are bounded evidence, not the full transcript.
MCP `assets_search` accepts the same `project_id` and `spec`, plus optional `asset_id`. Its compact results expose `matches` on each asset. In REST, search one asset with `POST /search/asset//run`, sending `project_id` and `spec`; the response is search metadata directly.
Search has no public pagination parameters or total-match count. Signal searches use a bounded candidate pool, and metadata filters can reduce it further. An empty result is not proof that the project contains no relevant file. Narrow the query, try a different channel, or use filter-only search for metadata criteria. MCP's `returned` and `available` describe the returned set, not an independent count of every possible match.
Use the result's folder path with `aspect download` to retrieve the media. You can replace the final filename with its asset UUID to avoid name ambiguity; keep the containing folders in the URL. Or [download a proxy](/docs/cli/proxies) for a smaller viewing copy.
# Background transfers
Source: https://aspect.inc/docs/cli/transfers
Run uploads and downloads in the background, inspect progress, wait for results, and cancel a transfer by ID.
Add `--detach` to an upload or download to start a background job. The command returns a transfer ID so you can close the terminal and check the job later on the same computer.
```bash theme={null}
aspect upload ./Footage "aspect://Acme/Documentary" --detach
aspect download "aspect://Acme/Documentary/Deliverables" ./delivery --detach
```
Keep the computer awake and connected, and keep local upload sources available until the job completes. A detached transfer survives closing its terminal; it is not a hosted job or a transfer that automatically resumes after a reboot.
## Inspect progress
```bash theme={null}
aspect transfer list
aspect transfer status
```
Replace `` with the ID printed when the job started. `list` shows tracked jobs on this computer. `status` shows the selected job's state and progress. Add `--json` for structured fields, including file counts, transferred bytes, and its result when finished.
## Wait for completion
```bash theme={null}
aspect transfer wait
```
`wait` stays attached until the transfer reaches a terminal state. A successful result exits with status `0`; a failed or cancelled result exits with status `1`. Starting a detached job successfully does not mean its files finished transferring.
For a script that extracts the returned ID and checks the final exit status, see [Scripts and AI agents](/docs/cli/automation).
## Cancel
```bash theme={null}
aspect transfer cancel
aspect transfer status
```
Cancellation requests the background runner to stop. Check its status afterward for the final outcome. Files that completed before cancellation remain at their destination.
## Mounted-file writes
`aspect transfer` tracks explicit CLI jobs started with `--detach`. Files saved through a mounted volume use the filesystem service's background upload queue.
Close applications' writable files, then run `aspect daemon status --json`. Check both `writeBackDrained` and `writeSyncSummary.failureCount`: a drained queue can still have recorded upload failures. A CLI transfer finishing does not establish that every mounted-file save has uploaded. See [Mount projects](/docs/cli/mounts#finish-work-and-unmount) for the completion checks.
# Troubleshooting
Source: https://aspect.inc/docs/cli/troubleshooting
Resolve authentication, path, mount, transfer, proxy, and offline-pin errors using Aspect's built-in diagnostics.
Start with the CLI's version, authentication source, and local diagnostics:
```bash theme={null}
aspect --version
aspect auth status
aspect doctor
aspect status
```
Add `--json` when collecting a result for a script. Commands report stable error codes as well as an explanation; use both to determine what to fix.
## Installation
| Symptom | What to check |
| - | - |
| `aspect` is not found | Open a new terminal after installation. On macOS/Linux, check that `~/.aspect/bin` is on `PATH`; on Windows, check `%USERPROFILE%\.aspect\bin`. |
| A documented flag is unknown | Check `aspect --version`, then `aspect --help`. Use `aspect upgrade` to install the latest published release. |
| `release_unavailable` during upgrade | Check your connection and access to GitHub Releases, then retry. |
| `downgrade_refused` | Your installed version is newer than the latest public release. Keep it, unless you deliberately intend to install that older public version. |
## Authentication
| Error or behavior | What to do |
| - | - |
| `not_logged_in` | Follow the message. On a workstation with the desktop app, open it and sign in. On a CLI-only machine, configure an API key. |
| `invalid_api_key` | Check that the key was copied correctly and has not been deleted. Create a replacement in Settings → API Keys if needed. |
| A supplied key appears to be ignored | Run `aspect auth status --json`. A signed-in desktop app takes precedence over an environment or stored key. |
| `auth logout` did not change the account | It only removes the stored CLI key and default workspace. Check the desktop session and `ASPECT_API_KEY`. |
| You can see a project but cannot download, upload, or organize it | Those actions require their own permissions. Have a workspace or project administrator check your access. |
See [Authentication and API keys](/docs/cli/authentication) for the complete sign-in order.
## Paths
| Code | What to do |
| - | - |
| `invalid_url` | Use `aspect:////`, quote names with spaces, and remove empty path segments. |
| `no_default_workspace` | Use an explicit workspace in the URL, or set one with `aspect workspace use`. |
| `not_found` | Use `aspect ls` to check each parent level and confirm the resource is visible to your account. |
| `ambiguous_name` | Replace the conflicting name with one of the IDs listed in the error. |
| `not_a_directory` | An intermediate path segment identifies a file. Correct the folder path. |
| `destination_not_directory` | Upload to a project or an existing directory, not a workspace or file. |
| `not_mountable` | Mount a project or directory, not an individual asset or workspace. |
## Mounts and the filesystem service
Run `aspect doctor` before retrying a failed mount. Install FUSE 3 on Linux or WinFSP on Windows when reported missing. On macOS, follow the mount-helper instructions. See [Installation](/docs/cli/installation).
Commands using `--json` do not prompt to install Linux or Windows prerequisites. Provision them before automated mount jobs.
If `daemon_owned_by_desktop` appears, restart or quit the signed-in Aspect app to manage its filesystem service. CLI daemon lifecycle commands cannot manage a service owned by that app.
For a standalone CLI service, `aspect daemon status` reports its state. Finish mounted-file work and check for pending uploads before using `aspect daemon restart`. A service restart can interrupt mounted applications.
If a save is not yet visible elsewhere, close its writable file in the application and run `aspect daemon status --json`. Require `writeBackDrained` to be `true` and `writeSyncSummary.failureCount` to be `0`, and resolve mount errors. Failed uploads can leave a drained queue, so check both fields. Missing fields do not confirm completion. See [Finish work and unmount](/docs/cli/mounts#finish-work-and-unmount).
## Uploads and downloads
| Symptom | What to do |
| - | - |
| Files were skipped | Both commands skip name conflicts by default. Use `--replace` for deliberate replacement or `--keep-both` for another copy. |
| `source_not_found` | Check that the local upload source still exists and is readable. |
| `destination_not_writable` | Check permissions and space on the local download destination. |
| `directory_conflict` | A path needed as a directory conflicts with a file, either in the remote upload destination or the local download destination. Choose another destination or resolve that conflict. |
| `network_timeout` or `network_unreachable` | Restore connectivity and rerun the transfer. Completed files are skipped by default. |
| A transfer has exit status `1` but still prints JSON | Inspect its `failed` entries or its terminal state/result. Partial failures use structured results too. |
| `transfer_not_found` | Check the ID and run `aspect transfer list` on the same computer. A newly launched detached job can briefly be absent before it writes its first status. |
Starting a job with `--detach` confirms launch, not successful delivery. Use `aspect transfer wait ` and inspect its result. A job whose background process stopped may need to be started again; it does not automatically resume after reboot.
## Proxies and offline pins
If `--variant stream_proxy` downloads fewer files than expected, the folder may contain assets without generated proxies. A single missing variant fails; folder downloads leave unmatched assets out. Check processing in Aspect and retry. There is no automatic fallback to originals. See [Proxies and previews](/docs/cli/proxies).
For offline access, wait until the required pins show `synced` in `aspect pin list`. `over_limit` requires changing pin selection or storage limits. `not_pinned` can mean the file is covered by a parent pin instead of having its own. Keep the project mounted before going offline; a new mount command needs API access.
## Get help
If the diagnostic message does not resolve the issue, contact the [Aspect community](https://discord.gg/NGca2AjGvM) with your operating system, `aspect --version`, the command you ran, and the error code. Redact API keys, signed download URLs, and private filenames before sharing output.
# Upload files
Source: https://aspect.inc/docs/cli/uploads
Upload files and directory trees to Aspect, control name conflicts, and handle interrupted or large transfers.
Use `aspect upload` to copy local files into an existing Aspect project or directory:
```bash theme={null}
aspect upload ./interview.mov "aspect://Acme/Documentary"
```
The destination is always the last argument. It must identify a project or an existing folder, and your account must have permission to upload there.
## Upload folders and multiple sources
```bash theme={null}
aspect upload ./Footage ./Audio ./notes.pdf "aspect://Acme/Documentary"
```
Folder uploads include the source folder's name and recreate its nested file paths. For example, `./Footage/Day 01/interview.mov` becomes:
```text theme={null}
aspect://Acme/Documentary/Footage/Day 01/interview.mov
```
You do not need a recursive flag. Symbolic links encountered inside a folder are skipped. Empty directories are not created independently of files.
The CLI creates the folders needed for the uploaded file tree **inside** the destination. The destination URL itself must already resolve; create a new destination project or folder in Aspect first.
## Choose what happens when a name exists
| Option | Behavior |
| - | - |
| No conflict flag | Skip files with an existing name at the destination. |
| `--replace` | Replace the existing file's content. |
| `--keep-both` | Keep the existing file and upload another copy with a distinct name. |
```bash theme={null}
aspect upload ./final.mov "aspect://Acme/Documentary/Deliverables" --replace
aspect upload ./review.mov "aspect://Acme/Documentary/Reviews" --keep-both
```
`--replace` and `--keep-both` cannot be combined. The default skip behavior compares destination conflicts; it does not make a changed local file into an automatic update. Choose `--replace` when you intend to upload revised content.
## Large uploads
The CLI streams file content and handles chunked uploading for you. To keep a job running after the terminal closes:
```bash theme={null}
aspect upload ./Footage "aspect://Acme/Documentary" --detach
aspect transfer list
```
Use the returned transfer ID to check progress or wait for completion. See [Background transfers](/docs/cli/transfers).
## Completion and interruptions
A foreground upload prints progress and a final count of uploaded, skipped, and failed files. Add `--json` for a result that a script can read:
```bash theme={null}
aspect upload ./Footage "aspect://Acme/Documentary" --json
```
The result includes `uploaded`, `skipped`, and a `failed` array containing each failed path and its error. A skipped file counts as a successful outcome; any file failure or interruption makes the command exit with a nonzero status.
Ctrl-C cancels a foreground job. You can rerun the same upload to skip files that already completed and try the remaining files again. This is a new transfer, not a promise to resume every partial file at its previous byte offset.
An upload completing means the source file has reached Aspect. Proxy generation and other media processing happen separately; a [streaming proxy](/docs/cli/proxies) may not be available immediately.
# Core concepts
Source: https://aspect.inc/docs/concepts/core-concepts
How workspaces, projects, directories, assets, and collections fit together in Aspect.
Aspect organizes everything in a simple hierarchy.
| Level | What it is |
| - | - |
| Workspace | Your organization - the top level that holds your team and all your projects |
| Project | A container for one body of work, like a production or a campaign |
| Directory | A folder inside a project, for organizing files (folders can nest) |
| Asset | A single file - video, image, audio, or document |
| Collection | A curated group of files that live anywhere in the project |
## Workspaces
A workspace is your organization's home in Aspect. Everyone on your team belongs to a workspace, and everything you store lives inside it. Who can see and do what is controlled at the workspace and project level - see [people and permissions](/docs/share-and-present/sharing-and-permissions).
## Projects
Projects are the main way to divide up your work. A documentary, an ad campaign, a client engagement - each gets its own project. Projects hold your folders and files, and access can be granted project by project, so people only see what's relevant to them.
### Storage tiers
Choose a storage tier when you create a project:
| Storage tier | Use it for |
| - | - |
| **Active Storage** | Media you want to work with through Instant Access, including mounted-drive streaming and pinning |
| **Cold Storage** | Long-term storage for media that does not need mounted-drive access |
Only Active Storage projects can be mounted through [Instant Access](/docs/instant-access/mount-a-project).
### Archiving a project
Archiving moves a project to the **Archived** section on the workspace homepage. It keeps the project out of the team's main project list until someone opens the archived project list.
You can archive projects in either Active Storage or Cold Storage. Archiving is only a change to how the workspace homepage is organized: the project's storage tier, files, and access permissions stay the same.
For example, an archived Active Storage project still supports mounting. An archived Cold Storage project still uses Cold Storage and cannot be mounted. Turn archiving off to return either project to the main project list.
## Directories
Directories are folders. They work the way folders do on your computer: they live inside a project, they can contain files and other folders, and you can nest them as deep as you need. Use them to keep raw footage, selects, and deliverables apart.
## Assets
An asset is a single file - a video, image, audio recording, or document. When you upload a file, it becomes an asset, and Aspect's AI automatically gets to work on it in the background: transcribing speech, understanding what's on screen, and preparing it for instant playback. There's nothing to configure or start - once it's done, the file is searchable and ready to review. See [AI Search](/docs/asset-intelligence/ai-search) for how to find files and matching moments, [uploading](/docs/getting-started/uploading-and-organizing) for how files get in, and [metadata](/docs/workflows/metadata) for the details Aspect tracks about each one. An asset is a single file - a video, image, audio recording, or document. When you upload a file, it becomes an asset, and Aspect's AI automatically gets to work on it in the background: transcribing speech, understanding what's on screen, and preparing it for instant playback. There's nothing to configure or start - once it's done, the file is searchable and ready to review. See [How AI indexing works](/docs/asset-intelligence/ai-indexing) for the full picture, [uploading](/docs/getting-started/uploading-and-organizing) for how files get in, and [metadata](/docs/workflows/metadata) for the details Aspect tracks about each one.
### Version stacks
When you have multiple versions of the same file (a rough cut, a revision, a final), Aspect can [stack them together as one asset](/docs/review-and-approve/versioning). You see the top version by default, but every earlier version stays a click away. No more `final_v3_FINAL.mp4` scattered across folders.
## Collections
A collection is a curated grouping of files and folders. Adding something to a collection doesn't move it - the original stays exactly where it is, and the collection just points to it. The same file can be in many collections at once.
Collections are great for pulling together the best takes from across a project, building a reel of selects, or gathering everything a client needs to review in one place. See the [collections guide](/docs/share-and-present/collections).
## Where to go next
Put these concepts into practice in a few minutes.
Find any moment in your library using plain English.
# AI Search and metadata
Source: https://aspect.inc/docs/faqs/ai-search-and-metadata
Common questions about search, transcription, and metadata in Aspect.
AI Search accepts natural-language questions and can use visual content, speech transcripts, tags, configured people and faces, comments, and metadata to find relevant files.
For supported media, a result can take you to the relevant moment in the file.
Yes. Uploaded media can be transcribed and indexed so spoken words are available to search.
Aspect supports technical, custom, and AI-generated metadata. Configured custom fields can be populated automatically based on the content of an asset.
No. Aspect does not use customer data to train AI models.
No. AI-generated information works alongside technical metadata embedded in a file and the custom fields configured for your workspace.
# Files, storage, and uploads
Source: https://aspect.inc/docs/faqs/files-storage-and-uploads
Common questions about adding, storing, and previewing media in Aspect.
Yes. You can upload files through the browser or the Aspect desktop app. The desktop app is generally better suited to large transfers and editing workflows.
Yes. Aspect can help customers migrate an existing media library. Contact the Aspect team to plan the migration for your storage setup and workflow.
Choose **Active Storage** or **Cold Storage** when you create a project.
Active Storage supports [Instant Access](/docs/instant-access/mount-a-project), including mounted-drive streaming and pinning. Cold Storage is for long-term storage and does not support mounting.
See [storage tiers](/docs/concepts/core-concepts#storage-tiers) for more details.
The project moves to the **Archived** section on the workspace homepage, keeping it out of the team's main project list. Open the archived project list to find it again.
You can archive either an Active Storage or a Cold Storage project. Archiving only changes where the project appears; it leaves the storage tier, files, permissions, and share links unchanged. An archived Active Storage project can still be mounted.
See [archiving a project](/docs/concepts/core-concepts#archiving-a-project).
Aspect creates smaller viewing copies so media can be previewed quickly. These proxies are used for watching and review. Editing applications work with the original media instead.
# Getting started
Source: https://aspect.inc/docs/faqs/getting-started
Answers to common questions about starting with Aspect.
Aspect brings media storage, access, review, sharing, search, and archive workflows into one cloud workspace.
Aspect is a cloud media workspace where teams can store, access, review, share, search, and archive media without moving it among several disconnected tools. See [Core concepts](/docs/concepts/core-concepts) for how workspaces, projects, assets, and collections fit together.
Most library, review, sharing, and organization work can happen in a web browser.
Use the Aspect desktop app when you need to mount a project as a drive, upload large amounts of media, or work with files in editing applications. Learn how to [mount your first project](/docs/instant-access/mount-a-project) or [upload and organize files](/docs/getting-started/uploading-and-organizing).
Yes. Aspect can help customers migrate an existing media library. Contact the Aspect team to plan the migration for your storage setup and workflow.
* [Upload and organize files](/docs/getting-started/uploading-and-organizing)
* [Organize revisions with Version Stacks](/docs/review-and-approve/versioning)
* [Sharing and permissions](/docs/share-and-present/sharing-and-permissions)
Yes. The Aspect desktop app is available for **Windows and macOS**. [Download the app](https://aspect.inc/download) for your operating system and sign in to access your workspace and projects.
Instant Access works on both platforms: mounted projects appear in File Explorer on Windows and Finder on macOS.
Open **Settings → People**, enter the person's email address, choose their workspace role, and send the invitation. If you choose **Limited Member**, give them access to the projects they need.
See [Invite a workspace member](/docs/share-and-present/sharing-and-permissions#invite-a-workspace-member) for the full steps and role descriptions.
Install and sign in to the [Aspect desktop app for macOS or Windows](/docs/apps/desktop), open the drive view, and select **Mount** next to your **Active Storage** project. Only Active Storage supports mounting.
The project appears as a drive in Finder on macOS or File Explorer on Windows. Open files from that drive in your usual applications; Instant Access streams the parts you need as you work.
See [Mount your first project](/docs/instant-access/mount-a-project) for setup, or [Pinning](/docs/instant-access/pin-files) to keep files available offline.
Create a folder for the incoming files and select **Share**. Create a share link with **Can add content** and **Can organize content** enabled, then copy the link and send it to the contributor.
They can open the link in their browser and upload files to the folder without joining your workspace.
See [Upload links](/docs/share-and-present/sharing-and-permissions#upload-links) for more details.
# Instant Access and offline work
Source: https://aspect.inc/docs/faqs/instant-access-and-offline-work
Common questions about mounting projects, caching media, and working offline.
Mounting makes an **Active Storage** project appear in Finder on macOS or File Explorer on Windows like a normal drive. Applications can begin opening media without downloading the entire file first.
Cold Storage projects cannot be mounted. Archiving a project only changes where it appears on the workspace homepage, so an archived Active Storage project can still be mounted. See [storage tiers and project archiving](/docs/concepts/core-concepts#storage-tiers).
No. Aspect caches the portions of files needed locally instead of downloading every file in the project.
You can configure the cache size and location. The cache can also be placed on an external drive.
Yes, for files and folders that you pin before going offline. Pinning downloads a complete local copy. Changes sync when you reconnect.
Plan ahead by pinning everything you will need while you still have a reliable connection.
Caching stores file data locally as you work and manages that space automatically. Pinning intentionally keeps a complete local copy available, including while you are offline.
# Permissions and administration
Source: https://aspect.inc/docs/faqs/permissions-and-administration
Common questions about workspace roles, project permissions, and outside collaborators.
A workspace role controls someone's overall access to the Aspect workspace. A project role controls what that person can do inside a specific project.
Project roles provide combinations of viewing, downloading, commenting, editing, and full access. Choose the lowest role that still lets the person complete their work.
Use a Limited Member role when a collaborator needs an Aspect account but should only see named projects.
Use a share link instead when the person only needs access to selected content and does not need to work inside the workspace.
No. Limited Members only see projects where access has been explicitly granted.
No. Workspace Owners have full access to every project. Only assign the Owner role to people who need to administer the complete workspace.
# Review and collaboration
Source: https://aspect.inc/docs/faqs/review-and-collaboration
Common questions about comments, versions, and review workflows.
Yes. Aspect supports timestamped and ranged comments for media. Reviewers can also use annotations, attach reference files, reply in threads, and receive review notifications.
Yes. Versions can be stacked together so reviewers can open the current revision, access available earlier revisions, and compare versions side by side.
Comments remain connected to the version on which they were created.
You can mark comments as approved during a review. To track an asset's overall review status, create a custom metadata field such as **Approval status** with options like **In review** and **Approved**, then update it as the review progresses.
See [Commenting](/docs/review-and-approve/commenting#approve-a-comment) for comment approvals and [Metadata](/docs/workflows/metadata) for custom fields.
No. Create a share link and enable commenting when an external reviewer needs to leave feedback without becoming a workspace member.
Yes. Comments, replies, annotations, and attachments remain connected to the asset and version being reviewed.
# Security and compliance
Source: https://aspect.inc/docs/faqs/security-and-compliance
Common questions about Aspect security, encryption, and compliance programs.
Learn how Aspect protects customer data and supports security and compliance reviews. Visit the [Aspect Trust Center](https://trust.aspect.inc) for detailed security documentation and reports.
Aspect has completed a SOC 2 Type II examination, maintains a HIPAA compliance program, and has completed an external GDPR assessment.
Customer data is encrypted with AES-256 at rest and TLS 1.2 or higher in transit.
Aspect maintains a HIPAA compliance program and can sign a Business Associate Agreement (BAA) when required. HIPAA was included in Aspect's joint SOC 2 and HIPAA Type I examination.
No. Aspect does not use customer data to train AI models.
# Sharing and guests
Source: https://aspect.inc/docs/faqs/sharing-and-guests
Common questions about share links, guest access, and collections.
No. Someone opening a share link is treated as a guest and does not need an Aspect account, a paid seat, or installed software.
Depending on the link, controls can include commenting, downloads, uploads, organizing, metadata visibility or editing, version access, a password, an expiration date, and video watermarking.
Create separate links when different audiences need different permissions.
Yes. Enable uploading on a share link when an outside contributor needs to send files into the selected shared location.
Only enable organizing or metadata editing when the contributor also needs those capabilities.
Aspect can attribute active guest actions such as comments, edits, and uploads. It does not identify someone who only opens or watches content through an anonymous share link.
Do not use a share link as proof that a specific person viewed a file.
A collection is a curated set of assets gathered for review or presentation without changing the original folder structure or moving the source files.
# Uploading and Organizing
Source: https://aspect.inc/docs/getting-started/uploading-and-organizing
Add files and folders to Aspect, keep them organized with directories and version stacks, and recover anything from the trash.
## Upload files and folders
Drag files or entire folders from your computer into any project or directory at [app.aspect.inc](https://app.aspect.inc). Aspect recreates your folder structure automatically, so a folder full of nested subfolders arrives exactly the way you organized it. You can also select the **+** button in the project or directory and choose an upload option.
While an upload runs, the upload panel shows progress for each file and for the batch as a whole. You can keep working (browse, search, and review) while uploads continue in the background.
Large files upload in small chunks, so a slow or interrupted connection never forces you to start over from zero. Failed uploads retry automatically. For faster uploads, especially large batches, use the [Aspect desktop app](https://aspect.inc/download).
### Upload with a two-finger click
Open the upload action from the context menu when you do not want to drag files into the browser.
### Pause and resume
Pause or resume a single file from the upload panel, or pause and resume the entire batch at once. Paused files wait until you resume them while everything else keeps uploading.
## Supported file types
Aspect accepts videos, images, audio files, and documents. Common examples:
| Type | Examples |
| - | - |
| Video | MP4, MOV, MKV, WebM, and many more |
| Image | JPEG, PNG, WebP, HEIC, camera RAW formats, SVG |
| Audio | MP3, WAV, M4A, and more |
| Documents | PDF, Word, PowerPoint, Excel |
Files Aspect can't index are still stored safely - you can organize, share, and download them like anything else.
If you are unsure whether Aspect can preview a format, test a sample file before uploading a large batch.
## Organize with directories
Create and arrange directories to keep production files in a predictable structure.
Inside a project you can:
Make a new directory anywhere in a project, and nest directories as deep as you need.
Drag assets and directories to a new location, or use the move action to pick a destination.
Rename assets and directories at any time.
Use directories to mirror your production structure and keep footage, project files, exports, and references in predictable locations.
For grouping files that live in different places without moving them, use [collections](/docs/share-and-present/collections).
## Version stacks
When you have several cuts or revisions of the same asset, [stack them into a single version stack](/docs/review-and-approve/versioning) instead of cluttering a directory with near-duplicates.
* Add an asset to another asset's stack to group them as versions of one item.
* Reorder versions inside a stack so the latest one sits on top - the top version is what everyone sees by default.
* Remove a version from the stack at any time to make it a standalone asset again.
## Trash and restore
Deleting an asset or directory moves it to the project's trash - nothing is lost immediately.
* **Restore** items from the trash to put them back.
* **Empty the trash** to permanently delete everything in it.
Emptying the trash is permanent. Once the trash is emptied, those files cannot be recovered.
## What happens after upload
The moment a file finishes uploading, Aspect's AI starts processing it in the background - transcribing speech, understanding what's on screen, and preparing it for instant playback. Use [AI Search](/docs/asset-intelligence/ai-search) to find files and matching moments after processing. The moment a file finishes uploading, Aspect's AI starts processing it in the background - transcribing speech, understanding what's on screen, and preparing it for instant playback. See [How AI indexing works](/docs/asset-intelligence/ai-indexing) for the full picture.
# iOS mobile app
Source: https://aspect.inc/docs/guides/ios-mobile-app
Upload, review, search, and share Aspect media from your iPhone.
Aspect Mobile brings your Aspect workspace to your iPhone so projects can keep moving when you are away from your desk.
Get Aspect Mobile from the Apple App Store.
Aspect Mobile requires iOS 17.0 or later and is designed for iPhone. Your workspace administrator may disable mobile access.
## What you can do
Use the iOS app to:
* Upload photos and videos from your camera roll or files.
* Review media and leave timestamped comments, replies, drawings, and markup.
* Work with revisions and version stacks.
* Receive notifications for new comments and revisions.
* Search visuals, transcripts, and comments with Aspect AI.
* Create secure share links and control whether recipients can view, comment, download, or have full access.
* Organize media by workspace, project, folder, and asset.
## Install and sign in
Open [Aspect Mobile in the Apple App Store](https://apps.apple.com/us/app/aspect-mobile/id6786935617) and download it to your iPhone.
Launch the app after installation finishes.
Sign in with the same Aspect account you use on the web.
Open the workspace and project where you want to browse, upload, or review media.
## Upload from your iPhone
Navigate to the project or folder where the media should be uploaded.
Open the upload action and choose media from your camera roll or files.
If iOS asks for permission, allow Aspect to access the photos or files you want to upload.
Choose the photos or videos you want to add and confirm the upload.
Confirm that the upload finishes and the new assets appear in the correct location.
Aspect processes uploads in the background, so large videos can continue moving while you use other apps. Keep a reliable network connection and check the upload status before closing Aspect for an extended period.
## Use notifications
Aspect Mobile can notify you when someone comments or uploads a new revision. See [Notifications](/docs/workspace-management/notifications) to configure activity-specific delivery preferences.
Allow notifications when iOS prompts you. To change the setting later, open **Settings > Notifications > Aspect** on your iPhone.
If notifications do not arrive, confirm that notifications are enabled in iOS and that your workspace permits mobile access.
## Review and approve on the go
Open an asset to play it and review the current version. Depending on your permissions, you can:
* Leave frame-accurate or timestamped comments.
* Reply to existing feedback.
* Add drawings and markup.
* Review other versions in a stack.
* Approve the selected version.
Before approving, confirm that you are viewing the intended version and that required feedback has been addressed.
## Search with Aspect AI
Use [AI Search](/docs/asset-intelligence/ai-search) in plain language to find media across visuals, transcripts, and comments. For example, ask for “the clip I last commented on” or describe the scene, person, object, or spoken phrase you need.
Search results can take you directly to the matching asset or moment.
## Share from your iPhone
Create a secure share link for an asset, then choose the access appropriate for the recipient. See [Sharing and permissions](/docs/share-and-present/sharing-and-permissions) for the complete set of share-link controls. Available permissions can include:
* View
* Comment
* Download
* Full access
Send the link through Messages, Slack, Teams, email, or another app. Review the link settings before sharing sensitive media.
## Mobile web and other devices
Aspect Mobile is a native iPhone app. If the native app is not available for your device, open [app.aspect.inc](https://app.aspect.inc) in a mobile browser.
There is currently no native Android app. Android users can use Aspect through their mobile browser.
## Troubleshooting
### The app cannot be installed
Confirm that the iPhone is running iOS 17.0 or later and that the App Store is available for the device and region.
### An upload does not start
Check that:
* Aspect has permission to access the selected photos or files.
* The device has a stable internet connection.
* You have permission to upload to the selected project or folder.
* Mobile access is enabled for the workspace.
### A large upload appears paused
Return to Aspect and check its progress. Keep the app open when possible and use a stable Wi-Fi connection for large media files.
### Notifications do not arrive
Open **Settings > Notifications > Aspect** and confirm that notifications are allowed. Also check Focus modes and other iOS settings that may silence alerts.
### You cannot access the workspace
Confirm that you signed in with the correct account. If the workspace still does not appear, ask a workspace administrator whether mobile access is enabled and whether your account has access.
## Best practices
* Confirm that uploads finish before deleting the source media from your phone.
* Keep feedback attached to the correct asset and version.
* Review share-link permissions before sending media.
# Welcome to Aspect
Source: https://aspect.inc/docs/index
A home for your team's media. Upload footage, let Aspect's AI watch, listen, and read everything, then search it in plain English.
## What is Aspect?
Aspect is one platform where your team can store files, stream footage to editors, send files out for review, and keep older media in Cold Storage. Upload your videos, images, audio, and documents, and Aspect's AI watches, listens, and reads everything for you. It transcribes speech, understands what's on screen, recognizes people, and pulls out metadata - automatically, in the background.
Once your files are indexed, you can find any moment by describing it in your own words. No filenames to remember, no tags to maintain. Then review footage with your team, leave comments, and share exactly what you want with clients - all from one place.
Get started in the browser at [app.aspect.inc](https://app.aspect.inc), or download the [Aspect desktop app for macOS or Windows](https://aspect.inc/download).
## Get started
Upload your first files and run your first search in a few minutes.
Learn how workspaces, projects, assets, and collections fit together.
## Everyday workflows
Drag and drop files or whole folders into a project.
See how uploaded files become ready for playback and search.
Find any moment across your library using natural language.
Play footage, scrub transcripts, and leave comments.
Group related files together without moving them.
See and edit the details Aspect knows about each file.
Send secure links to people outside your workspace.
Invite teammates and control who can see what.
## Go further
Find, organize, and answer questions about your media with Aspect Agent.
A faster way to work with large files on macOS or Windows.
Review, search, and share your Aspect files from your phone.
Browse your Aspect projects like a local drive in Finder on macOS or File Explorer on Windows.
Build custom tools and integrations on top of Aspect with the developer API.
# Cache management
Source: https://aspect.inc/docs/instant-access/manage-cache
Control how much local storage Aspect uses to keep streamed media ready for faster access.
The Aspect desktop app for **macOS and Windows** uses a local cache to make files from a [mounted project](/docs/instant-access/mount-a-project) faster to open and reuse.
When you open or scrub through a file, Aspect streams the parts your application requests and stores frequently accessed data on your computer. The next time you use the same content, Aspect can read it from the cache instead of downloading it again.
Caching happens automatically. You can control how much disk space the cache may use and where it is stored from the Aspect desktop app.
## How the cache works
Mounting a project does not download the entire project to your computer.
As you work, Aspect:
1. Streams the parts of a file your application requests.
2. Prefetches data it expects the application to need next.
3. Stores accessed data in the local cache.
4. Reuses cached data when you return to the same part of a file.
5. Removes older cached data when space is needed.
This lets you begin working with large files without waiting for a complete download.
Cached data is a temporary local copy. Removing cached data does not delete or change the original file stored in Aspect.
## View cache usage
Use the Aspect desktop app to see how much local storage the cache is using.
Launch the Aspect desktop app on your computer.
Open the desktop app settings and find the local cache settings.
Check the current cache limit, how much space Aspect is using, and where the cache is stored.
The amount of cached data changes as you work. Opening new files adds data to the cache, while automatic eviction removes older data when Aspect needs space.
## Increase the cache size
A larger cache lets Aspect keep more recently accessed media on your computer.
This can improve performance when you:
* Return to the same footage repeatedly.
* Scrub through long timelines.
* Switch between several large files.
* Work on the same project over multiple sessions.
* Have enough local disk space for active media.
Open the Aspect desktop app settings and find the local cache controls.
Confirm that your computer has enough free storage for a larger cache.
Leave space available for your operating system, creative applications, project files, exports, and other local work.
Choose a larger cache size.
The cache limit is the maximum amount of local storage Aspect may use for automatically cached data.
Apply the new limit if prompted. Aspect can now retain more recently accessed data before older cached content is removed.
Increase the cache gradually. A cache large enough for your active footage is usually more useful than assigning all available disk space to Aspect.
## Decrease the cache size
Reduce the cache limit when you need to recover local disk space.
Open the local cache settings in the Aspect desktop app.
Reduce the maximum amount of storage Aspect may use.
Aspect removes older cached data as needed to stay within the new limit.
Reducing the cache does not remove files from Aspect. Content that is no longer cached can be streamed again the next time you open it.
## Choose a cache size
The best cache size depends on your available storage and the media you work with.
Consider:
* The size of your active project
* The number of files you use regularly
* The length of your editing sessions
A larger cache can reduce repeated network use, but it does not need to contain the entire project.
For example, a project may contain several terabytes of footage while the cache holds only the portions you recently opened or scrubbed.
## Change the cache location
You can choose where Aspect stores cached data.
Changing the location can help when:
* Your primary disk has limited free space.
* Another supported storage location has more capacity.
* You want to separate media caches from your system disk.
* Your creative applications already use most of the primary disk.
Open the Aspect desktop app settings and find the cache location.
Select a supported storage location with enough available space.
Make sure Aspect can write to the selected location and that it remains available while you work.
Apply the new cache location if prompted.
If the selected cache location becomes unavailable, Aspect may need to stream data again or ask you to choose another location.
## Automatic cache eviction
Aspect manages cached data automatically.
When the cache approaches its configured limit, Aspect removes stale data while keeping recently used content available. This process is called cache eviction.
Automatic eviction:
* Keeps cache usage within the configured limit.
* Prioritizes recently accessed content.
* Recovers space from content you are no longer using.
* Does not delete or modify original files in Aspect.
* Does not remove files from the project.
If evicted data is needed again, Aspect streams it from the project and adds it back to the cache.
## Cache and network usage
The cache reduces repeated network activity, but the first access to uncached content still requires an internet connection.
When you open a file:
* Cached parts are read from local storage.
* Uncached parts are streamed from Aspect.
* Newly accessed data may be added to the cache.
* Prefetching may retrieve upcoming parts before the application requests them.
A larger cache can help when your connection is inconsistent because more previously accessed data remains local. It does not guarantee that a complete file will be available offline.
For guaranteed offline access, pin the file or folder.
Download complete files or folders and keep them available offline.
## Cache and pinning
Caching and pinning are different.
| Cache | Pinning |
| - | - |
| Happens automatically as you access files | Starts when you choose to pin content |
| May contain only parts of a file | Downloads the complete file or folder |
| Older data may be removed automatically | Content remains local until you unpin it |
| Designed to improve normal streaming performance | Designed for offline or guaranteed local access |
| Controlled by the cache size limit | Requires enough space for the complete pinned content |
Do not rely on cached data for offline work. Pin everything you need before disconnecting from the internet.
## What happens when the cache is full
Reaching the cache limit does not stop you from opening files.
Aspect automatically removes older cached data to make room for newly accessed content. If you return to something that was removed, Aspect streams it again.
If content is being streamed repeatedly, consider:
* Increasing the cache size.
* Confirming that the cache location has enough free space.
* Pinning the files you use most often.
* Checking whether another application is clearing or restricting local storage.
* Reviewing your internet connection.
## Cache best practices
* Keep enough free disk space for your operating system and your creative applications.
* Use a larger cache when repeatedly working with the same footage.
* Store the cache in a location that remains available while you work.
* Pin files when you need guaranteed offline access.
## Troubleshoot cache performance
If files that were previously fast begin streaming again:
* Confirm that the cache location is still available.
* Check whether the cache limit was reduced.
* Check whether older data was automatically evicted.
* Confirm that your computer has available disk space.
* Make sure the Aspect desktop app is running.
* Check your internet connection for uncached content.
## Related guides
Learn how streaming, prefetching, caching, and synchronization work together.
Keep complete files and folders available offline.
Make an Aspect project available as a drive on your computer.
# Mount your first project
Source: https://aspect.inc/docs/instant-access/mount-a-project
Mount an Aspect project on macOS or Windows and open cloud files directly in your desktop applications.
Instant Access lets you mount an Aspect project as a drive on your computer using the Aspect desktop app for **macOS or Windows**.
Once mounted, the project's folders and files appear in Finder on macOS or File Explorer on Windows like content on an SSD or NAS. You can open files in Premiere Pro, DaVinci Resolve, Final Cut Pro (macOS), or any other application that works with files on your computer.
Aspect streams the parts of each file your application needs, so you can begin working without downloading the entire project first.
## Before you start
To mount a project, you need:
* A macOS or Windows computer with the Aspect desktop app installed
* An active Aspect account
* Access to the project you want to mount
* An internet connection for files that are not stored locally
* A project using **Active Storage**
The mounted drive is managed through the Aspect desktop app and is **not available from a browser** alone.
Install the Aspect desktop app for your operating system and sign in before mounting a project.
## Mount a project
Mounting a project makes its files available through Finder while Aspect manages cloud access and local caching.
Launch Aspect on your macOS or Windows computer.
Select the **drive icon** in the left sidebar, then find the project you want to mount.
You must have access to the project before you can mount it.
Select **Mount**.
Aspect connects the project to your computer. Mounting usually takes only a few moments.
After mounting finishes, select the mounted path shown for the project. On macOS, the path may look like `/Volumes/ProjectName`. On Windows, use the drive letter shown by Aspect, such as `Z:`.
Aspect reveals the project in Finder on macOS or File Explorer on Windows. You can browse its complete folder structure immediately, even when the project contains terabytes of media.
Open a file directly from the mounted drive or import it into your editing application.
Aspect begins streaming the parts of the file your application requests.
The mounted drive is available on macOS and Windows.
## Find the project on your computer
Mounted Aspect projects appear in your file explorer as drives.
Mounted Aspect projects appear as drives in Finder on macOS and File Explorer on Windows.
* **macOS:** Look under **Locations** in the Finder sidebar. You can also add the project to your Finder sidebar favorites.
* **Windows:** Open File Explorer and find the mounted project using the drive letter shown in Aspect.
* **Both platforms:** Select the mounted drive when opening or importing a file from another application.
The mounted project keeps the same folder structure you see in Aspect.
If you mount more than one project, each project is available as its own mounted drive.
## Open files in creative applications
The mounted project behaves like a normal drive, so no editing plug-in is required.
You can:
* Import and edit footage in Premiere Pro, DaVinci Resolve, or Final Cut Pro (macOS).
* Open images or audio in your preferred creative application.
* Save project files and exports directly to the Aspect drive.
Point your application at the mounted Aspect drive and open the file as you would from an SSD or NAS.
## How streaming works
Mounting a project does not download the entire project to your computer.
When an application opens a file, Aspect streams only the parts of the file being requested. Intelligent prefetching anticipates which parts may be needed next, helping playback and scrubbing continue smoothly.
This means you can:
* Begin opening a file without waiting for a full download.
* Work with files larger than the available space on your computer.
* Keep working from the same shared files as the rest of your team.
The original files remain stored in Aspect.
## Local caching
As you open and use files, Aspect stores frequently accessed data in a local cache.
Cached data makes repeated access faster because Aspect does not need to stream the same parts of a file again.
Caching happens automatically. Use [Cache management](/docs/instant-access/manage-cache) to configure the cache from the desktop app, including:
* How much disk space the cache can use
* Where the cache is stored
* How much space is currently in use
Aspect automatically removes stale cached data when space is needed while keeping recently used content available.
Cached files are not guaranteed to be fully available offline. Use pinning when you need the complete file or folder stored locally.
## Keep files available offline
Pin a file or folder when you need guaranteed access without an internet connection. See [Pinning](/docs/instant-access/pin-files) for how to download complete files or folders and confirm they are ready for offline work.
Pinning downloads the complete content and keeps it on your computer.
Use pinning when:
* Working on a plane
* Traveling without reliable internet
Changes made to pinned files synchronize with Aspect after your computer reconnects to the internet.
## Cache and pinning
Caching and pinning serve different purposes:
| Feature | How it works |
| - | - |
| Caching | Stores recently accessed parts of files automatically |
| Pinning | Downloads and keeps the complete file or folder locally |
| Best for caching | Normal connected work and repeated access |
| Best for pinning | Offline work or guaranteed local availability |
You do not need to pin every file before editing. For normal connected work, Aspect streams and caches content automatically.
## Save changes back to Aspect
Files on the mounted drive remain connected to the project in Aspect.
When you save a change, Aspect synchronizes it back to the project automatically. Other team members working from the same project can then access the updated file.
Changes that synchronize include:
* Editing and saving files
* Deleting content
* Saving project files or exports to the drive
When a teammate adds content to the project, it also appears on your mounted drive.
## Check sync status
The Aspect desktop app provides transfer and sync details on both macOS and Windows, including anything that needs your attention.
On macOS, Finder also shows status badges on files that are uploading or synchronizing. Use these indicators or the desktop app to check whether a saved change has finished uploading.
Before closing the app or disconnecting from the internet, confirm that important changes have finished synchronizing.
## Work with your team
Everyone who mounts the same project works from the same shared folder structure and files.
For example:
1. An editor opens footage from the mounted project.
2. The editor saves a new timeline or export to the Aspect drive.
3. Aspect synchronizes the update so teammates can access the new content.
This avoids passing drives, copying entire projects, or maintaining separate versions of the same files.
See how your team can use a mounted Aspect project with Adobe Premiere Pro.
## Mount multiple projects
You can mount multiple Aspect projects at the same time.
Each mounted project appears as a separate drive, so you can move between productions without downloading them locally.
Only mount the projects you are actively using if you want to keep your mounted drives and local cache easier to manage.
## Storage tiers and archived projects
Choose **Active Storage** or **Cold Storage** when you create a project. Only Active Storage projects support mounting through Instant Access.
Archiving a project moves it to the **Archived** section on the workspace homepage. You can archive projects in either storage tier; this only changes where the project appears in the workspace.
An archived Active Storage project can still be mounted. Open the archived project list to find it, then mount it as usual. Cold Storage projects cannot be mounted, whether or not they are archived.
See [storage tiers and project archiving](/docs/concepts/core-concepts#storage-tiers).
## Troubleshoot mounting
### The Mount option does not appear
Check that:
* You are using the Aspect desktop app rather than only the browser.
* The desktop app is running and signed in.
* You have access to the project.
* The project uses Active Storage.
* The desktop app is up to date.
If you still cannot mount the project, ask your workspace administrator to confirm your access.
### The project does not appear in Finder or File Explorer
Try the following:
* Confirm that the project shows as mounted in the desktop app.
* On macOS, check the **Locations** section of the Finder sidebar. On Windows, check File Explorer.
* Close and reopen the Finder or File Explorer window.
* Confirm that the Aspect desktop app is still running.
* Restart the desktop app and mount the project again.
### A file opens slowly
Aspect must stream content that is not already cached or pinned.
Check that:
* Your internet connection is active.
* The desktop app is running.
* Your cache has available disk space.
* The configured cache location is connected and writable.
For guaranteed local access, pin the file or folder before working with it.
### Changes are not appearing for teammates
Check the file's sync status in the Aspect desktop app. On macOS, you can also check its status badge in Finder.
Confirm that:
* The save completed successfully.
* The desktop app is still running.
* Your computer is connected to the internet.
* There is enough disk space for the local cache.
* The transfer panel does not show an error.
Wait for synchronization to finish before moving, renaming, or deleting the file again.
### A pinned file is not available offline
Confirm that the file or folder finished downloading before disconnecting from the internet.
Pinning must complete before the content becomes fully available offline.
## Related guides
Manage the location and storage limit of your local cache.
Add files and complete folder structures to a project.
Learn how workspaces, projects, directories, and assets fit together.
Find the right footage, then open the original file from the mounted drive.
# Understanding how Instant Access works
Source: https://aspect.inc/docs/instant-access/overview
Learn how Instant Access streams, caches, and synchronizes your Aspect files on macOS and Windows.
Instant Access makes an Aspect project appear as a drive on your computer using the Aspect desktop app for **macOS or Windows**.
The files remain stored in Aspect, but you can browse them in Finder on macOS or File Explorer on Windows and open them in your creative applications like files on an SSD or NAS. You can begin working without downloading the entire project first.
## Open a project on your computer
After mounting a project, it appears as a drive in Finder on macOS or File Explorer on Windows.
You can:
* Browse the project's folders and files.
* Open media in Premiere Pro, DaVinci Resolve, Final Cut Pro (macOS), Avid, CapCut, and other applications.
* Open images, audio, and documents in their usual applications.
* Save project files and exports directly to Aspect.
* Create, rename, move, and delete files or folders.
* Mount multiple projects at the same time.
No editing plug-in or special application setup is required.
Connect an Aspect project to your computer and open it from the mounted drive.
## Stream files without downloading the project
Mounting a project does not download everything to your computer.
When you open a file, Aspect streams the parts your application needs. As you play or move through the file, Aspect continues retrieving the upcoming content.
This lets you:
* Begin opening large files without waiting for a complete download.
* Browse projects that are larger than the available space on your computer.
* Work with the same project files as the rest of your team.
* Avoid maintaining a separate local copy of the complete project.
The original files remain stored in Aspect.
## Automatic local caching
As you work, Aspect stores recently accessed content in a local cache on your computer.
The cache makes repeated access faster. For example, a section of video you have already played may open more quickly the next time you return to it.
Caching happens automatically. You do not need to choose which parts of a file are stored.
When the cache approaches its configured limit, Aspect removes older cached content to make room for newly accessed content. Removing cached data does not delete the original file from Aspect.
Control how much local storage Aspect uses and where the cache is stored.
## What kind of internet connection do I need?
Instant Access works best with a stable internet connection.
The connection you need depends on the files you are working with. Smaller or more compressed files generally require less bandwidth. Large camera originals, high-quality media, and projects that play several videos at once may require a faster and more stable connection.
There is no single connection speed that works for every project.
Before an important editing session, open a few files from the actual project and test playback in the application you plan to use.
## Improve playback performance
If playback pauses or takes time to load:
* Check that your internet connection is stable.
* Pin important files or folders before the session.
* Pause unrelated large uploads or downloads.
If you expect a slow or unreliable connection, pin the files you need while you are still connected to a faster network.
## Use Wi-Fi or Ethernet
Wi-Fi may work well for many projects, especially after frequently used content has been cached.
For large media files, multiple video streams, or important editing sessions, wired Ethernet can provide more predictable performance.
You do not need to choose a specific Wi-Fi band or calculate a file's technical requirements. Test the project using your normal setup. If playback is not consistent, use Ethernet or pin the media before working.
## Pin files for offline access
Caching does not guarantee that a complete file is available offline. The cache may contain only the parts you previously accessed, and older cached content may be removed automatically.
Pin a file or folder when you need the complete content stored locally.
Pinned content:
* Downloads in full.
* Remains available without an internet connection.
* Stays local until you unpin it.
* Synchronizes changes after you reconnect.
* Requires enough disk space for the complete file or folder.
Use pinning before traveling, working at a remote location, or starting a session where the network may be unreliable.
Keep complete files and folders available for offline work.
## Save changes back to Aspect
Files on the mounted drive remain connected to the Aspect project.
When you save a change, Aspect synchronizes it back to the project. Other people with access can then see the updated file.
Changes that synchronize include:
* Editing and saving files
* Adding new files
* Creating folders
* Renaming content
* Moving files or folders
* Deleting content
* Saving project files or exports
Check sync status in the Aspect desktop app before closing the app or disconnecting from the internet. On macOS, Finder also shows sync badges.
If your connection drops while a change is being uploaded, Aspect keeps the previous complete version available. The incomplete update is not shown to teammates.
## Work with your team
Everyone who mounts the same project works from the same shared files and folder structure.
For example:
1. An editor opens footage from the mounted project.
2. The editor saves a timeline or export to the Aspect drive.
3. Aspect synchronizes the change to the project.
4. A producer, colorist, or other teammate sees the updated content.
This reduces the need to pass physical drives, copy complete projects, or maintain separate versions of the same files.
## Work while offline
Instant Access normally requires an internet connection for content that is not stored locally.
Before going offline:
1. Pin the files and folders you need.
2. Wait for pinning to finish.
3. Confirm that the files open from the mounted drive.
4. Leave enough local space for changes and exports.
Changes made while offline remain on your computer. After you reconnect and open the Aspect desktop app, the changes synchronize back to the project.
## On-site shared cache
Some organizations may have an Aspect-managed on-site shared cache.
With a shared cache, the first person at a location retrieves content from Aspect. Other editors on the same local network may then reuse that data instead of downloading it separately.
A shared cache can help teams working from the same office reduce repeated internet transfers.
Shared-cache availability depends on your workspace and deployment. Contact Aspect to confirm whether it is available for your organization.
## Storage tiers and archived projects
You choose a storage tier when creating a project:
* **Active Storage** supports Instant Access, including mounted-drive streaming, caching, and pinning.
* **Cold Storage** is for long-term storage and does not support mounting through Instant Access.
You can separately **archive** a project in either storage tier. This moves it to the **Archived** section on the workspace homepage, keeping it out of the team's main project list until they open the archived project list. Its storage tier, files, and permissions stay the same.
An archived Active Storage project can still be mounted. Turning archiving off on a Cold Storage project returns it to the main project list, but it remains in Cold Storage and cannot be mounted.
See [storage tiers and project archiving](/docs/concepts/core-concepts#storage-tiers).
## Streaming, caching, and pinning
| Method | Best for |
| - | - |
| Streaming | Opening cloud files without downloading them in full first |
| Automatic caching | Repeated access during normal connected work |
| Pinning | Offline work and guaranteed local availability |
| Shared caching | Multiple editors working from the same location |
Most connected workflows use streaming and automatic caching together. Pin only the files and folders that must remain fully available locally.
## Related guides
Connect an Aspect project to your computer and open it from the mounted drive.
Control how much local storage Aspect uses for cached media.
Keep complete files and folders available offline.
# Pinning
Source: https://aspect.inc/docs/instant-access/pin-files
Keep complete files and folders on your macOS or Windows computer for offline work and guaranteed local access.
By default, Aspect streams files from the cloud as you open them. Pinning in the desktop app for **macOS or Windows** downloads the complete file or folder and keeps it on your computer.
Use pinning when you need guaranteed access without an internet connection or want important media stored locally before a session.
## When to pin content
Pin files or folders when you are:
* Preparing to work on a plane
* Traveling without reliable internet
* Preparing for an editing session with large media
You do not need to pin everything before using Instant Access. For normal connected work, Aspect streams and caches content automatically.
## Before you pin
Pinned content is downloaded in full, so it requires enough local disk space for the complete file or folder.
Before pinning:
* Check the size of the content.
* Confirm that your computer has enough free storage.
* Leave additional space for your operating system and creative applications.
* Keep the Aspect desktop app running.
* Use a stable internet connection for large downloads.
* Confirm that the project is mounted and available.
A pinned folder requires enough space for all the files inside it.
Pinning a large folder may use significantly more storage than the automatic cache, which may contain only the parts of files you recently accessed.
## Pin a file
Launch the Aspect desktop app and confirm that you are signed in.
Open the project containing the file you want to keep locally.
Mount the project first if it is not already available on your computer. Follow [Mount your first project](/docs/instant-access/mount-a-project) if you need to connect it in the desktop app.
Find and select the file you want to make available offline.
Choose **Pin**.
Aspect begins downloading the complete file to your computer.
Keep the desktop app running until the file shows that pinning is complete.
Do not disconnect from the internet until the complete file is available locally.
## Pin a folder
Pin a folder when you need all of its contents available locally.
Check which files the folder contains and estimate how much local storage the complete folder requires.
Open the mounted project and select the folder you want to keep locally.
Choose **Pin**.
Aspect begins downloading the files inside the folder.
Keep the desktop app running and connected to the internet while the download continues.
Confirm that the folder has finished pinning before going offline.
Files added to a project by other people may require additional downloading before they are available locally. Check the pinning status before disconnecting.
## Check how much space pinning requires
Pinned content uses local storage based on the full size of the selected files.
For a single file, plan for at least the complete file size.
For a folder, add together the sizes of the files inside it. Leave additional free space for:
* Creative application caches and temporary files
* Proxies, render files, exports, and other pinned content
Before pinning a folder, right-click it and select **Show Info**. The **Size** value shows how much local storage the complete folder requires.
Avoid filling your system disk completely. Creative applications and your operating system need free space for temporary files and normal operation.
## Track pinning progress
The Aspect desktop app shows the progress of local downloads.
Before going offline, confirm that:
* The pinning operation finished.
* The selected files or folders show as available locally.
* The desktop app does not show a transfer error.
* Your computer has enough remaining disk space.
* You can open the required files from the mounted drive.
Opening a partially pinned folder does not guarantee that every file inside it is available offline.
## Work while offline
After pinning finishes, you can open the content from the mounted Aspect drive without an internet connection.
Pinned content works like other files on your computer. You can:
* Open media in your editing application.
* Scrub through footage.
* Open project files.
* Edit documents.
Changes made while offline remain on your computer until Aspect reconnects.
Only content that finished pinning is guaranteed to be available offline. Unpinned files may require an internet connection even if you opened them previously.
## Sync changes after reconnecting
When your computer reconnects to the internet, Aspect synchronizes changes back to the project.
Connect your computer to a stable network.
Make sure the Aspect desktop app is running and signed in.
Aspect uploads changes made while you were offline.
Confirm that your saves and new files finished synchronizing before closing the app or disconnecting again.
Other people with access to the project can see the updated files after synchronization completes.
## Unpin content
Unpin files or folders when you no longer need guaranteed offline access.
Open the project and select the pinned file or folder.
Choose **Unpin**.
Allow Aspect to release local data as it manages the cache and check that the expected disk space becomes available.
Unpinning does not delete the original content from Aspect. The file remains in the project and can be streamed again when you are online.
After content is unpinned, Aspect may keep recently accessed parts in the automatic cache until that space is needed.
## Pinning and caching
Pinning and caching both use local storage, but they serve different purposes.
| Cache | Pinning |
| - | - |
| Happens automatically as files are accessed | Starts when you choose to pin content |
| May contain only parts of a file | Downloads the complete file or folder |
| Older cached data may be removed automatically | Content remains available until you unpin it |
| Improves normal streaming performance | Provides guaranteed offline access |
| Controlled by the cache size limit | Requires space for the complete pinned content |
Use caching for normal connected work. Use pinning when you must have complete files available locally.
Control how much local storage Aspect uses for automatically cached media.
## Decide what to pin
You may not need to pin an entire project.
To reduce storage use, pin only:
* The folder for the current edit
* The original media needed for the session
* Project files and supporting documents
* Music, graphics, or reference files needed offline that must remain available locally
Leave files you do not need offline unpinned and stream them when needed.
## Pinning large media
Large video files and folders may take time to download fully.
Before pinning large media:
* Check the total size.
* Connect to a stable network.
* Connect your computer to power.
* Keep the desktop app running.
* Confirm that the cache or storage location remains connected.
* Begin the download early enough for it to finish before you leave.
Pinning does not compress or reduce the size of the original content.
## Pinning, storage tiers, and archived projects
Pinning through Instant Access requires an **Active Storage** project. Choose Active Storage when creating a project you plan to mount and pin. **Cold Storage** projects do not support mounting or pinning through Instant Access.
Archiving a project only moves it to the **Archived** section on the workspace homepage. It leaves the storage tier unchanged, so an archived Active Storage project can still be mounted and pinned.
Open the archived project list to find the project, then mount it and pin the files you need. See [storage tiers and project archiving](/docs/concepts/core-concepts#storage-tiers).
## Troubleshoot pinning
If pinning does not start:
* Confirm that the desktop app is running.
* Confirm that you are signed in.
* Confirm that the project is mounted.
* Confirm that you have access to the content.
* Confirm that the project uses Active Storage.
* Check your internet connection.
* Check available local storage.
If pinning stops before completion:
* Keep the desktop app open.
* Reconnect to the internet.
* Confirm that the local storage location is available.
* Check for a transfer error in the desktop app.
* Free local disk space if the selected content is too large.
If pinned content is unavailable offline:
* Confirm that pinning finished before you disconnected.
* Confirm that you are opening the correct mounted project.
* Confirm that the pinned file still exists at the expected location.
* Reconnect and allow Aspect to finish any incomplete download.
## Related guides
Manage automatic cache usage, size, and location.
Learn how streaming, prefetching, caching, and synchronization work.
Add files and organize the content you want to make available locally.
Mount an Aspect project and open it in Finder on macOS or File Explorer on Windows.
# Troubleshooting
Source: https://aspect.inc/docs/instant-access/troubleshooting-draft
Resolve common mounting, streaming, cache, and offline-access issues in the Aspect desktop app.
Use these checks when an Instant Access project or file is not behaving as expected.
Do not delete files from a mounted project to free local cache space. Deletions synchronize with Aspect. Use the desktop app's cache controls instead.
Check the requirements and steps for mounting a project.
Check available storage and the location of your local cache.
## The Mount option does not appear
Check that:
* You are using the Aspect desktop app, not only the browser.
* The app is running, up to date, and signed in to the correct account.
* You have access to the project.
* The project uses **Active Storage**, which supports mounting through Instant Access.
Ask your workspace administrator to confirm your access if the project is still unavailable. Archived Active Storage projects can still be mounted; look in the **Archived** project list. Cold Storage projects do not support mounting.
## A mounted project does not appear on your computer
Confirm that the project shows as mounted in the desktop app. Check **Locations** in Finder on macOS or your drives in File Explorer on Windows.
Keep the Aspect desktop app running, then close and reopen the Finder or File Explorer window. Use the mounted path shown in the desktop app to reveal the project.
## A file opens or plays slowly
Content that is not already stored locally needs to stream from Aspect. Check that:
* Your internet connection is active and the desktop app is running.
* There is available disk space for the cache.
* The configured cache location is connected and writable.
For complete local availability, [pin the file or folder](/docs/instant-access/pin-files) and wait for the download to finish before working offline.
## A pinned file is not available offline
Pinning must finish downloading the complete file or folder before you disconnect. Automatic caching alone does not guarantee offline access.
Reconnect to the internet, keep the desktop app running, and check the download status and available disk space. Confirm that pinning has completed before disconnecting again.
Download complete files or folders and check that they are ready for offline work.
## Changes are not appearing for teammates
Check the file's sync status and the desktop app's transfer details. Confirm that the save completed, your computer is online, the app is running, and the transfer panel does not show an error.
Wait for synchronization to finish before moving, renaming, or deleting the file again. Keep the app open and connected until important changes have finished uploading.
## The issue continues
Contact your workspace administrator with the project name, affected file or folder, your operating system and desktop app version, and the exact error message. Include the checks you have already tried. Do not share passwords or API keys.
# Quickstart
Source: https://aspect.inc/docs/quickstart
Install Aspect on macOS or Windows, upload files, mount a project, and find cloud media on your computer.
This walkthrough works on **macOS and Windows** and takes you from uploading media to finding the exact file on your computer.
The key moment comes at the end: search across your cloud library, then use **Open in mount** to reveal the matching file locally in Finder on macOS or File Explorer on Windows.
Download the [Aspect desktop app](https://aspect.inc/download) and install the version for your operating system.
The desktop app provides the mounted drive used in this walkthrough and is also the best option for large uploads.
Create a project and choose **Active Storage**, or open an existing Active Storage project. This storage tier supports the mounted-drive steps below. Add a few videos, images, audio files, or documents.
You can upload through the browser or the desktop app. Upload an entire folder if you want Aspect to preserve its nested folder structure.
You can keep browsing while uploads continue in the background. See [Upload and organize files](/docs/getting-started/uploading-and-organizing) for the complete workflow.
In the desktop app, select the **drive icon** in the left sidebar, find your project, and select **Mount**.
After mounting finishes, select the mounted path shown for the project, such as **/Volumes/ProjectName** on macOS. Aspect reveals it in Finder or File Explorer, where its folders and files appear like content on another drive without requiring you to download the entire project first. For setup details, streaming behavior, and troubleshooting, see [Mount your first project](/docs/instant-access/mount-a-project).
Return to Aspect in your browser and use [AI Search](/docs/asset-intelligence/ai-search) to find something inside the files you uploaded.
Describe what you need in plain English, such as "a wide shot of the beach" or "the interview where someone mentions the budget."
Once indexing is complete, Aspect can find matching files and relevant moments using visual content, speech, and metadata.
Right-click the search result and choose **Open in mount**.
Aspect reveals the exact file inside the mounted project in Finder on macOS or File Explorer on Windows. You can then open it with any compatible application on your computer.
This is the core Instant Access workflow: use the cloud to store, index, and search your media, then work with the same files through normal local file paths.
## Next steps
* Learn what happens after upload in [Uploading and Organizing](/docs/getting-started/uploading-and-organizing#what-happens-after-upload).
* Explore upload controls in [Upload and organize files](/docs/getting-started/uploading-and-organizing).
# Commenting
Source: https://aspect.inc/docs/review-and-approve/commenting
Leave precise feedback on videos, images, and documents.
Comments keep feedback attached to the content being reviewed. External reviewers can comment through a [share link](/docs/share-and-present/sharing-and-permissions) when commenting is enabled.
## Approve a comment
Mark a comment as approved to record agreement during a review. Review the comment, its replies, and the relevant media before approving it.
Use a reply when you need to explain the decision or identify a particular revision. If your team also tracks an asset's overall review status, update its custom metadata field separately.
See the [simple review workflow](/docs/workflows/simple-review-workflow) for recording decisions and confirming the final revision.
## Keep comments internal
Turn on **Internal** before adding a comment if the discussion should stay private to your team.
Internal comments are useful when:
* Producers and editors are discussing work in progress
* A team needs to review a concern before replying to a client
* Feedback includes private production details
To create an internal comment:
1. Open comments on the asset.
2. Select **Internal** before submitting the comment.
3. Add the comment as usual.
4. Confirm that the internal state is visible on the comment.
A normal comment may be visible to external reviewers who have comment access. Check the setting before including private information.
## Comment on a video
Move to a moment or select a time range, then add your feedback. You can also attach a file, draw on the frame, or make the comment internal.
Selecting the comment returns playback to the relevant moment or range.
## Draw on a frame
Pause on the frame, mark the relevant area, and add a short explanation. Available markup includes freehand drawing, arrows, boxes, and circles.
## Comment on images and documents
For images, select the area you want to discuss. For documents, open the relevant page or highlight a specific passage. The comment stays connected to that location.
## Work with comments
* **Attach a file** to provide a reference image, graphic, storyboard, or other supporting material.
* **Reply** to keep related feedback in one thread.
* **Mention a teammate** with `@` when you need their attention.
* **React** to acknowledge feedback without adding another reply.
* **Edit** your comment when you need to correct or clarify it.
* **Copy a link** to send someone directly to the comment.
* **Resolve** a comment when the change is complete or the discussion no longer needs action.
Resolved conversations remain available in the asset's history and can be reopened.
## Comments and versions
Comments stay with the version where they were created. Reviewers can [compare versions](/docs/review-and-approve/versioning) while keeping each review round connected to the correct media.
## Notifications and permissions
Aspect supports in-app and email notifications for comments, replies, mentions, and conversation updates. Delivery depends on each person's [notification preferences](/docs/workspace-management/notifications).
Commenting is a separate permission. Workspace members receive access through project permissions, while guests receive it through the share link.
Control who can view, comment on, and download shared content.
## Use Aspect Agent with comments
Aspect Agent can search comments, summarize feedback, and post or reply to comments on your behalf.
For example:
* `What feedback have people left on this cut?`
* `Find every unresolved comment about the logo.`
* `Leave a comment asking the editor to check the color grade.`
Review the selected assets and proposed comment before approving an action.
Search feedback and complete multi-step review workflows.
## Comments in archived projects
Browser previews and comments remain available when media is archived. You can read, add, reply to, resolve, and share comments without restoring the source media.
Mounted-drive access requires Active Storage. Archiving a project leaves its storage tier unchanged; see [storage tiers and archiving](/docs/concepts/core-concepts#archiving-a-project).
## Related guides
Play media, inspect transcripts, and review versions.
Compare revisions while keeping feedback with the correct version.
Send content to external reviewers with controlled permissions.
Search comments, summarize feedback, and post replies.
# Sharing Security
Source: https://aspect.inc/docs/review-and-approve/sharing-security
Protect share links with permissions, passwords, expiration dates, and video watermarks.
Share links let clients, reviewers, and outside collaborators access selected Aspect content without joining your workspace.
Each link has its own permissions and security settings. Create separate links when different audiences need different levels of access.
## Create a protected share link
Configure a separate link with the access and security settings required for its audience.
Select the asset, folder, collection, or project, then open **Share**.
Select **Create share link** and add an optional internal name so your team knows who the link is for.
Enable only the actions the recipient needs. Depending on the content, available controls can include **Comments**, **Downloads**, **View versions**, **View metadata**, and **Edit metadata**.
Under **Security**, add password protection, choose a link expiration, or select a watermark for sensitive video playback.
Confirm the shared content, permissions, and security settings, then select **Create link**. Test the recipient experience before sending it.
Available permissions can vary based on what you share. Folders and other shared locations may also offer contribution or organization controls.
## Choose the minimum permissions needed
Every share link allows recipients to view the selected content. Additional controls determine what else they can do.
* **Comments** lets reviewers [leave precise feedback](/docs/review-and-approve/commenting) on shared content.
* **Downloads** lets recipients download the shared files.
* [**View versions**](/docs/review-and-approve/versioning) lets recipients open earlier versions when available.
* **View metadata** exposes the metadata fields selected for the link.
* **Edit metadata** lets recipients change the [metadata fields selected for editing](/docs/workflows/metadata).
Leave a permission off unless the recipient needs it. Create separate links for reviewers, contributors, and delivery recipients instead of giving one link broad access.
Sharing a folder, collection, or project includes the content inside it. Check the complete set before sending it.
## Add password protection
Select **Add password** when access should require more than possession of the link.
Anyone opening the link must enter the password before viewing the shared content. Send the password separately from the link when practical.
A password protects the link, but it does not confirm the identity of the person entering it. Anyone who has both the URL and password may be able to use the link.
## Set a link expiration
Use **Link expiration** when access should end automatically.
Choose an available preset or select a specific expiration date. After the selected date and time, the link stops providing access until its settings are changed.
Expiration works well for temporary review periods, limited delivery windows, and unreleased material.
## Add a watermark to video playback
Watermarking adds a visible identifier to video played through a share link without changing the original file. Create a watermark while configuring a share link or from **Settings → Content Security**, then select it under the link's **Security** settings.
Learn how to create a watermark and configure its text, position, color, opacity, rotation, size, and weight.
## Manage or revoke access
Share-link settings can be updated after a link is created.
* Change permissions when a recipient's role changes.
* Add or update a password or expiration date.
* Change or remove the selected watermark.
* Disable a link to pause access.
* Delete a link when its URL should no longer work.
Changes apply to everyone using that link. Create a new link when a new audience needs different access.
## Understand guest visibility
Aspect can attribute active actions such as comments, edits, and uploads when identifying information is available.
Aspect does not identify someone who only opens or watches content through an unauthenticated share link. Do not treat a share link, watermark field, or anonymous view as proof that a specific person accessed the content.
## Best practices
* Create a separate link for each audience or purpose.
* Enable only the permissions recipients need.
* Use a password and expiration date for sensitive or temporary access.
* Review **Downloads** separately when using a video watermark.
* Test the link in a private browser window before sending it.
* Disable or delete links that are no longer needed.
Learn how workspace roles, project roles, and share-link permissions work together.
# Version Stacks
Source: https://aspect.inc/docs/review-and-approve/versioning
Organize revisions, compare cuts, and keep feedback connected to the correct version.
Version stacks group revisions of the same asset into one item. Reviewers can open earlier cuts, compare two versions, and see the feedback attached to each review round.
## Create and update a version stack
[Upload each cut as a separate asset](/docs/getting-started/uploading-and-organizing) in the same project or directory, then wait for the uploads to finish.
Drag one revision onto another related asset. Aspect groups them into one version stack.
Upload the new cut, then drag it onto the existing stack.
Open the stack and confirm that the intended latest revision appears first.
## Manage versions
Open the stack's version controls to view, reorder, or remove revisions.
* Select an earlier revision and view its review activity.
* Reorder versions so the intended revision opens by default.
* Remove a version that was added to the wrong stack.
Removing a version from a stack makes it a standalone asset again. It does not permanently delete the file.
## Compare two versions
Use comparison mode to review two cuts side by side and check changes to editing, graphics, color, audio, captions, or client revisions.
Open the versioned asset in the viewer.
Start a comparison and select the earlier and newer revisions.
Inspect both versions side by side before starting another review round.
## Feedback stays with its version
Comments, annotations, attachments, replies, and resolved conversations remain connected to the version where they were created. Moving between versions shows the feedback for the selected revision instead of mixing review rounds together.
Leave precise feedback and keep each conversation connected to the relevant media.
## Share a version stack
You can send versioned media to external reviewers with a share link.
Before sending it:
1. Confirm that the intended revision opens by default.
2. Choose whether recipients can comment, download, view metadata, or access earlier versions.
3. Test the link before sending it.
Do not assume every recipient should see earlier cuts. Review the link's permissions before sharing a version stack with a client.
Create secure review links and control what recipients can view or do.
## Important behavior
* Version stacks are for intentional review rounds, not file backup or recovery.
* Saving over a working project file does not automatically create a new version in the stack.
* Review activity remains attached to the relevant revision.
* Archived versioned media remains available for browser review, comments, metadata, AI Search, and share links.
* Mounted-drive access requires Active Storage. Archiving a project leaves its storage tier unchanged; see [storage tiers and archiving](/docs/concepts/core-concepts#archiving-a-project).
Contact Aspect support if you need help recovering an earlier saved state of a working file.
## Best practices
* Keep only related revisions in the same stack.
* Confirm the latest version before requesting review or sharing.
* Compare the new cut with the previous review round.
* Keep earlier versions when their feedback provides useful context.
## Related guides
Upload files, folders, and new revisions to Aspect.
Play media and inspect each review round in the browser.
Add frame-accurate feedback, markup, attachments, and replies.
Send versioned media to clients and external reviewers.
# Viewer and review
Source: https://aspect.inc/docs/review-and-approve/viewer-and-review
Preview media, navigate transcripts, compare versions, and review creative work in your browser.
The Aspect viewer brings playback, transcripts, comments, comment approvals, and versions together in one place.
Open an asset to review it without downloading the original file first. When you are finished, share it with teammates or external reviewers and keep their feedback connected to the media.
## Open an asset
Select any asset to open it in the viewer.
Aspect can preview:
* Videos
* Audio
* Images
* Documents
Videos and audio use streaming previews prepared during indexing. Images and documents also open directly in the browser.
The original source file remains stored in Aspect and is not changed by the browser preview.
## Review video and audio
Use the playback controls to find the exact moment you want to review.
For video, you can:
* Play and pause with Space.
* Use J, K, and L to move backward, pause, and play forward.
* Step through footage one frame at a time.
* Scrub the timeline to move quickly through the clip.
* Select a comment on the timeline to return to that moment.
These controls make it easier to inspect edits, graphics, color, audio, captions, and other changes.
## Use the transcript
When a video or audio file contains speech, open its transcript to follow what was said.
You can:
* Follow the highlighted text during playback.
* Select a word to jump to that moment.
* Search within the transcript.
* Move between search results.
* Export the transcript for use outside Aspect.
Learn how Aspect creates searchable transcripts for video and audio.
## Leave feedback
Anyone with comment access can leave feedback directly on an asset.
Comments can be connected to:
* A moment or time range in a video
* A specific location on an image
* A page or highlighted passage in a document
Reviewers can also draw on a paused video frame, attach reference files, reply in threads, mention teammates, and react to comments.
Comments appear with the version where they were created, preserving the feedback from each review round.
Learn how to add precise feedback, drawings, attachments, and replies.
## Keep discussions internal
Mark a comment as internal when it should only be visible to your team.
Internal comments are useful when clients and teammates are reviewing the same asset but your team needs a separate conversation.
Check whether a comment is internal before including private production information. A normal comment may be visible to external reviewers with comment access.
## Resolve completed feedback
Resolve a comment thread when the requested work has been completed.
Resolved comments remain in the asset's history and can be reopened if the issue returns.
Use a reply when you need to add context or confirm a change. Resolve the thread only when it no longer requires action.
## Review different versions
Version stacks keep related revisions together as one asset.
Open a version stack to:
* Move between earlier and later cuts.
* Review the comments associated with each version.
* Compare two versions side by side.
The latest version appears by default, while earlier review rounds remain available.
Organize revisions, compare cuts, and preserve each round of feedback.
## Track review decisions
You can mark comments as approved during a review. Use a reply to explain the decision or identify the revision being discussed.
For an asset's overall review status, create a custom metadata field such as **Approval status**, with options such as **In review**, **Changes requested**, and **Approved**. Update that field as your team's review progresses.
Before setting the status to **Approved**, confirm that you are viewing the intended revision and that the responsible reviewer has accepted it. Review new revisions and update the metadata when the review status changes.
Record agreement on a comment and keep it connected to the relevant revision.
## Share content for review
Use a share link to send an asset, folder, collection, or project to someone outside your workspace.
Guests can open the link in their browser without an Aspect account or installed software.
Depending on the link's permissions, guests may be allowed to:
* View content
* Leave comments
* Download files
* Upload content
* See metadata
* View earlier versions
Before sending a review link, confirm that the latest version is displayed and that recipients have only the permissions they need.
Give teammates and external reviewers the appropriate level of access.
## Download an original file
The viewer uses a streaming preview, but the original source file remains stored in Aspect.
If you have download permission, you can download:
* A single asset
* Multiple selected assets
* The contents of a directory
Use the download panel to track the progress of larger or multi-file downloads.
Downloading requires download access. If the download option is unavailable, ask a workspace Owner or someone with Full Access to review your permissions.
Follow a review from first playback through feedback, revisions, comparison, and final approval.
## Related guides
Add precise feedback, drawings, attachments, and replies.
Organize revisions and compare two cuts side by side.
Control what teammates and external reviewers can access.
Navigate media using a searchable transcript.
# Collections
Source: https://aspect.inc/docs/share-and-present/collections
Curate files and folders into a presentation or review set without changing their original locations.
Collections let you gather related files and folders into one curated set.
Use a collection to prepare content for a client review, presentation, delivery, or internal workflow without moving or copying the original files.
## How collections work
A collection points to files and folders in their original locations.
When you add something to a collection:
* The original item stays in its existing folder.
* The item is not copied or duplicated.
* Your project folder structure does not change.
* The same item can appear in more than one collection.
* Removing the item from the collection does not delete the original.
For example, footage can remain in its production folders while selected clips are gathered into a client review collection.
## Create a collection
Gather related assets into one reusable view without moving their original files.
1. Open the project containing the files you want to collect.
2. Create a collection from the collection area.
3. Give the collection a clear name.
4. Add a short description explaining its purpose.
5. Add the files and folders you want to include.
6. Review the collection before sharing it.
Use names that explain what the collection contains, such as:
* Approved Social Deliverables
* Interview Selects
## Add files and folders
A collection can contain individual assets, complete folders, or a combination of both.
There are two ways to add content.
### Use the actions menu
1. Select one or more files or folders.
2. Open the actions menu.
3. Choose the option to add them to a collection.
4. Select the destination collection.
You can select multiple items and add them together.
### Use drag and drop
Drag files or folders from the file view onto a collection in the side panel.
Adding an item to a collection does not move it out of its original folder.
## Add an item to multiple collections
The same asset can appear in more than one collection.
For example, an approved campaign video could appear in:
* A client delivery collection
* A social media collection
* A collection of approved brand assets
Each collection points to the same original asset. Aspect does not create another copy of the file.
## Arrange a collection
Items in a collection can have their own order, separate from the order of the original project folders.
Arrange the content in the sequence you want recipients to see it.
For example, a delivery collection might be ordered as:
1. Final video
2. Short social versions
3. Caption files
Changing the order in a collection does not change the original files or folders.
## Rename a collection
You can rename a collection at any time.
Open the collection and select its title to edit it.
Renaming a collection does not rename or move the files inside it.
## Add a description
Use the collection description to explain:
* What the collection contains
* What the recipient should review
* When feedback is due
* Which files are approved
* How the content should be used
Keep the description short. Add detailed feedback directly to the relevant asset.
## Remove an item
Removing an item from a collection does not delete the original file or folder.
1. Open the collection.
2. Select the files or folders you want to remove.
3. Open the actions menu.
4. Choose the option to remove them from the collection.
The items remain available in their original project locations.
## Delete a collection
Deleting a collection removes the curated set, but it does not delete the original files or folders inside it.
Before deleting a shared collection, check whether anyone is still using its share link.
## Brand a collection
Add branding when presenting a collection to clients, partners, or stakeholders.
Branding options can include:
* A description
* A background image
* Brand colors
* A logo
* Other visual styling
Branding changes how the collection is presented. It does not change the original files or folder structure.
Use [Display Customization](/docs/workspace-management/display-customization) to adjust your internal library view. These controls are separate from collection branding.
## Share a collection
Every collection can be shared through a link.
People who receive the link can open it in their browser without an Aspect account or installed software.
To share a collection:
1. Confirm that the collection contains only the intended files and folders.
2. Open the collection.
3. Choose **Share**.
4. Create a share link.
5. Choose what recipients are allowed to do.
6. Add a password or expiration date when needed.
7. Test the link before sending it.
8. Copy and send the link.
## Choose recipient permissions
Every share link allows recipients to view the shared content.
You can also choose whether they can:
* Leave comments
* Download files
* Upload content
* Organize content
* View metadata
* Edit metadata
* View earlier versions
Only enable the permissions each recipient needs.
Learn more in [Sharing and permissions](/docs/share-and-present/sharing-and-permissions).
## Protect a shared collection
Share links can include additional protections.
### Password
Require recipients to enter a password before opening the collection.
### Expiration date
Set a date and time when the link should stop working.
### Watermark
Apply watermarked playback when reviewing sensitive video. Turn off **Downloads** separately if recipients should not receive the original file.
### Disable or delete a link
Disable a link to stop access temporarily.
Delete the link when access should be permanently revoked.
Protect share links with permissions, passwords, expiration dates, and video watermarks.
## Common uses for collections
### Selects
Gather the best takes from a shoot, even when they are stored in different folders.
### Client review
Add the videos, images, or documents that need feedback and share the complete set with one link.
### Deliverables
Create a collection containing the approved files that should be delivered to a client or partner.
### Presentations
Arrange assets into a focused presentation for a stakeholder, campaign, pitch, or portfolio.
### Reusable content
Keep a collection of frequently used brand assets, b-roll, graphics, or approved media.
## Collections in archived projects
Archiving a project moves it to the **Archived** section on the workspace homepage. Its collections remain available, and existing collection share links continue to follow their permissions.
This applies to projects in either Active Storage or Cold Storage. Archiving leaves the storage tier unchanged. See [archiving a project](/docs/concepts/core-concepts#archiving-a-project).
## Related guides
Control what teammates and external reviewers can access and do.
Protect share links with passwords, expiration dates, permissions, and watermarks.
Collect precise feedback and keep conversations attached to the relevant media.
Organize revisions and keep feedback connected to the correct version.
# Embed videos
Source: https://aspect.inc/docs/share-and-present/embed-videos
Add an Aspect video player to another website using a share link.
Aspect videos can be embedded on another website so visitors can watch without leaving the page.
Embedding is available for individual videos that can be previewed in the browser.
There are two ways to embed an Aspect video:
* [**Embed with code**](#embed-with-code): Copy the iframe embed code from Aspect and paste it into an HTML or custom embed block.
* [**Embed with a link**](#embed-with-a-link): Paste the Aspect embed link into a platform that supports external video URLs or link previews.
## How video embedding works
An embedded video uses the Aspect browser player.
The player loads the browser-playable version prepared by Aspect during indexing. It does not load or change the untouched original file.
The embed is connected to an Aspect share link. The link controls access to the shared video.
## Before embedding a video
Confirm that:
* The video has finished uploading.
* Aspect has prepared a browser preview.
* The video plays correctly in the Aspect viewer.
* You selected the correct asset and version.
* The share link is active.
* The share-link permissions are appropriate for the website's audience.
* The video is approved for publication.
## Embed with code
Copy the iframe embed code from Aspect and paste it into an HTML or custom embed block.
1. Open the individual video in Aspect.
2. Open the sharing controls.
3. Create a new share link or select an existing one.
4. Review the link's permissions and protections.
5. Open the available embed option.
6. Copy the embed code provided by Aspect.
7. Open your website editor or content management system.
8. Add an HTML or embed block.
9. Paste the Aspect embed code into the block.
10. Preview the webpage and test playback.
11. Publish the webpage when everything works correctly.
The exact name of the embed field depends on the website platform you use. It may be labeled Embed, HTML, Custom HTML, Code, Video embed, or External media.
## Embed with a link
Use this option when the website accepts a video URL, link preview, or external-media link instead of HTML code.
1. Open the individual video in Aspect.
2. Open the sharing controls.
3. Create a new share link or select an existing one.
4. Review the link's permissions, password, expiration, and watermark settings.
5. Copy the share link.
6. Open your website editor or content management system.
7. Add a video, external media, URL, or link-preview block.
8. Paste the Aspect share link into the URL field.
9. Preview the webpage and test playback as a visitor.
10. Publish the webpage when playback and access work correctly.
If the platform displays only a clickable link instead of a player, use the embed-code method or confirm that the platform supports external video links.
## Choose the correct share link
Choose the option that best fits the platform where you are publishing. Use the embed code when the platform accepts HTML or custom embed blocks. Use the share link when it only supports URLs, link previews, or external media. Preview the result to confirm that playback and access permissions work as expected.
Create a separate share link for a public embed instead of reusing a private review link.
Before copying the embed code, check:
* Whether downloading is allowed
* Whether metadata is visible
* Whether earlier versions are visible
* Whether the link has a password
* Whether the link has an expiration date
* Whether watermarked playback is enabled
The share-link settings remain separate from the website where the player is embedded.
Learn more in [Sharing and permissions](/docs/share-and-present/sharing-and-permissions).
## Password-protected videos
A share link can be protected with a password.
Before embedding a password-protected video, test the complete experience as a visitor. Make sure the protection is appropriate for an embedded player and that recipients know how to obtain the password.
Do not place a password directly on a public webpage next to the protected video.
## Expiring embeds
A share link can have an expiration date.
If the video should remain available on the website, make sure the link does not expire unexpectedly.
Use expiration for:
* Temporary campaign pages
* Limited review periods
* Event pages
* Short-term presentations
* Time-sensitive announcements
Review expiration dates before publishing or updating the webpage.
## Watermarked playback
Watermarking can be enabled through the share-link settings.
Use watermarked playback when sensitive video needs a visible playback identifier. Review the link's **Downloads** permission separately if recipients should not receive the source file.
Test the embedded player after enabling watermarking. Learn how to [create and configure a watermark](/docs/share-and-present/watermarking).
## Test the embedded player
Always test the final webpage before sending it to visitors.
Check that:
* The correct video appears.
* The player loads.
* Playback starts normally.
* The full player is visible.
* The video is not cut off by the page layout.
* Fullscreen playback works when available.
* The player works on desktop and mobile.
* The link has not expired.
* Password protection works as expected.
* The intended permissions are active.
Test the webpage in a private browser window when possible. This helps you see the page as someone outside your Aspect workspace would see it.
## Update access to an embedded video
The embedded player depends on its Aspect share link.
Open the video's sharing controls when you need to:
* Review the link
* Change its permissions
* Add or update a password
* Change its expiration date
* Disable the link
* Delete the link
Changes to the share link affect access to the shared video.
Turning the share-link toggle off and back on in Aspect does not force an external website to refresh. The toggle changes the link's access state, but it does not change the embed code, reload a page that is already open, or clear caching managed by the website or visitor's browser.
After changing the toggle, reload the published webpage and test it in a private browser window. If the website uses page or CDN caching, you may also need to republish the page or clear that cache before visitors see the updated access state.
## Disable an embed
To stop access temporarily, disable the share link used by the embed.
You can enable the link again later if the video should return.
## Permanently revoke access
Delete the share link when the embed should no longer provide access to the video.
After deleting the link, remove the embed code from the external website as well.
## Embed on a website builder
Most website builders provide an embed or custom HTML block.
The general workflow is:
1. Add an embed block to the page.
2. Paste the code provided by Aspect.
3. Save the page.
4. Preview the result.
5. Adjust the block or container if the player does not fit.
6. Publish the page.
Refer to your website platform's documentation if it blocks external embeds or requires additional approval for custom code.
## Troubleshoot an embed
### The player does not appear
Check that:
* The embed code was copied completely.
* The code was pasted into an embed or HTML block.
* The share link is active.
* The video can be previewed in Aspect.
* The website platform allows external embedded players.
### The video is unavailable
Check whether:
* The share link was disabled.
* The share link was deleted.
* The link reached its expiration date.
* Password protection was added or changed.
* The underlying asset is still available.
### The player is cut off
Review the size of the embed block or its surrounding page container.
The available sizing controls depend on the website platform.
### The wrong video appears
Return to Aspect and confirm that the embed was created from the correct individual video and share link.
Create a new embed if the wrong asset was selected.
## Embedding and viewer tracking
Do not use an embedded player as proof that a specific person watched the video.
Aspect does not identify passive viewers of an unauthenticated share link.
Use comments, replies, or another explicit response when you need someone to confirm that they reviewed the content.
## Best practices
* Embed only approved videos.
* Confirm that you selected the correct version.
* Create a dedicated share link for the embed.
* Review permissions before publishing.
* Avoid exposing internal metadata.
* Test the embed as an external visitor.
* Check desktop and mobile playback.
* Review expiration dates.
* Use password protection for sensitive content.
* Disable or delete the link when access should end.
* Remove outdated embed code from the external website.
* Do not claim individual view tracking.
## Related guides
* [Sharing and permissions](/docs/share-and-present/sharing-and-permissions)
* [Collection branding](/docs/share-and-present/collections#brand-a-collection)
* [Collections](/docs/share-and-present/collections)
* [Versioning](/docs/review-and-approve/versioning)
# Sharing and permissions
Source: https://aspect.inc/docs/share-and-present/sharing-and-permissions
Give teammates and external reviewers the right level of access to your Aspect content.
Aspect provides two ways to give someone access:
* **Workspace access** is for teammates and ongoing collaborators who need an Aspect account.
* **Share links** are for clients, reviewers, and other guests who only need access to specific content.
Use workspace access when someone regularly works inside Aspect. Use a share link when someone only needs to view, review, download, or contribute to selected content.
## Choose the right access method
| Person | Recommended access |
| - | - |
| Internal teammate | Workspace Member |
| Freelancer working on selected projects | Limited Member |
| Client reviewing a cut | Share link with commenting |
| Client viewing a final delivery | View-only share link |
| Partner downloading deliverables | Share link with downloading |
| Contributor sending files | Share link with uploading |
| Public website visitor | Embedded player |
Guests do not need an Aspect account or any software. Send them a share link instead of adding them to the workspace.
## Workspace roles
A workspace role controls someone's overall access to the Aspect workspace.
| Role | What it means |
| - | - |
| Owner | Has full administrative access to the workspace and every project. Owners can manage people, workspace settings, and projects. |
| Member | Can create projects and access workspace projects using each project's default role. |
| Limited Member | Can only access projects where they have been given permission. Other projects remain hidden. |
Use **Limited Member** when someone should only have access to specific projects.
For example, a freelance editor working on one campaign can be added as a Limited Member and given access only to that campaign's project.
Only give the Owner role to people who need to manage the entire workspace.
## Invite a workspace member
Use this workflow for teammates and ongoing collaborators who need to sign in to Aspect.
Open **Settings → People** for your workspace.
Enter the person's email address.
Select Owner, Member, or Limited Member.
If you selected Limited Member, add the person to the projects they need.
Review the access and send the invitation.
## Project roles
A project role controls what someone can do inside a specific project.
| Role | Access |
| - | - |
| Full Access | View, download, comment, edit, and share |
| Editor | View, download, comment, and edit |
| Commenter | View, download, and comment |
| Downloader | View and download |
| Viewer | View only |
Choose the lowest level that still allows the person to complete their work.
For example:
* Give a producer **Full Access** if they need to manage content and sharing.
* Give an editor the **Editor** role.
* Give a stakeholder the **Viewer** role if they only need to see content.
## Default project access
Each project has a default role.
Workspace Members receive that role automatically unless their access is changed for the specific project. You can give someone more access on a project they lead or set them to No Access on a project they should not see.
Limited Members do not receive access through the default role. They only see projects where access has been explicitly granted.
## Permissions apply throughout a project
A person's project role applies to the content inside that project, including its folders, assets, and collections.
For example, someone with the Editor role can edit content throughout the project. Someone with the Viewer role can open the project but cannot comment, download, or make changes.
To understand what a workspace member can do with an asset, check their role on the project containing it.
## Manage access to a project
Each project has a People area where you can review and update access.
From there, you can:
* See who has access.
* Review each person's role.
* Add a workspace member to the project.
* Change someone's project role.
* Remove someone's project access.
Open the project whose access you want to manage.
Go to the project's People or access settings.
Select the workspace member whose access you want to change.
Choose the appropriate project role or remove access.
Review the person's new access before closing the settings.
Workspace Owners always have full access to every project. Their project access cannot be reduced.
## Share content with a guest
**Share a file**
Share links give people outside your workspace access to selected content.
You can create a link for:
* A single asset
* A folder
* A collection
* A project
A person who opens a share link is a **guest**. Guests do not need an Aspect account, a paid seat, or installed software.
Sharing a folder, collection, or project gives the guest access to the content inside it. Review the contents before sending the link.
## Create a share link
**Create a share link**
Open the asset, folder, collection, or project you want to send.
Choose **Share**.
Create a new share link for the selected content.
Choose what people using the link are allowed to do.
Add a password, expiration date, or watermark when needed.
Confirm that the correct content, permissions, metadata, and versions are included.
Copy the link and send it to the recipient.
## Share-link permissions
Every share link allows recipients to view the shared content. You can add other permissions depending on what the guest needs to do.
Available controls can include:
| Permission | What it allows |
| - | - |
| Comment | Leave feedback on shared assets |
| Download | Download the shared files |
| Can add content | Add files through the link |
| Can organize content | Help organize contributed content |
| View metadata | See the metadata fields included with the link |
| Edit metadata | Update permitted metadata fields |
| View versions | Open earlier revisions in a version stack |
Not every link needs every permission.
For a typical client review link:
* Allow viewing.
* Enable commenting.
* Leave downloading off unless the client needs a copy.
* Leave uploading and organizing off unless the client is contributing files.
* Hide internal metadata.
* Decide whether the client should see earlier versions.
* Add a password or expiration date for sensitive content.
Create separate links for separate audiences. A client, editor, and delivery partner can each receive a link with different permissions.
## View-only links
Use a view-only link when someone only needs to see the content.
This is useful for:
* Presentations
* Final approvals
* Stakeholder updates
* Portfolio reviews
* Completed deliverables that should not be downloaded
Guests can open the content in their browser but cannot comment, download, or make changes unless those permissions are enabled.
## Review links
Enable commenting when clients or other reviewers need to leave feedback.
Guests can then:
* Comment on media.
* Reply in comment threads.
* Add reactions.
* Attach reference files.
* Review the shared versions available to them.
They do not need to join the workspace.
Learn how reviewers leave precise, time-based feedback.
## Download links
Enable downloading when a guest needs the original files.
For shared folders and collections, recipients with download permission can download multiple items together.
Do not enable downloading when the recipient only needs to review the content.
## Upload links
Create an upload link when someone outside the workspace needs to send files to your team.
Create a folder in the project where you want to receive the files.
Select the folder and choose **Share** to create a share link.
Enable **Can add content** and **Can organize content**.
Copy the link and send it to the contributor. They can open it in their browser and upload files to the folder without joining your workspace.
Upload access is useful for:
* Collecting footage from a production partner
* Receiving client assets
* Gathering submissions
* Receiving graphics, audio, or documents
* Collecting deliverables from a freelancer
Enable metadata editing as well if the contributor needs to update metadata on the uploaded content.
## Share versioned media
A share link can control whether guests see earlier versions of an asset.
Before sending a version stack:
1. Confirm that the latest cut appears by default.
2. Decide whether the guest should see earlier review rounds.
3. Check that internal metadata is hidden.
4. Enable commenting if feedback is needed.
5. Confirm whether downloading should be allowed.
Do not assume every reviewer should have access to earlier cuts.
Organize revisions and keep feedback connected to the correct version.
## Control metadata visibility
Share links can control which metadata guests can see.
Before sending a link, review the visible fields and hide information that is only intended for your team.
Internal metadata might include:
* Production notes
* Licensing details
* Internal status fields
* Costs
* Rights information
* Private contact details
* Internal review decisions
Only enable metadata editing when the guest is expected to help maintain that information.
## Protect a share link
### Add a password
Add a password when the shared content is sensitive or intended for a limited group.
Anyone opening the link must enter the password before viewing the content.
Send the password separately from the link when practical.
### Set an expiration date
An expiration date makes the link stop working automatically after the selected date and time.
Use an expiration date for:
* Temporary client reviews
* Limited delivery windows
* Unreleased campaigns
You can use a preset period or select a custom expiration.
### Enable watermarking for video
Enable watermarking on a share link to place a visible identifying mark over video during playback. The watermark adds traceability without permanently changing the original asset.
Watermarking is configured for the share link, not automatically applied to every asset or share. Combine it with link permissions, password protection, and an expiration date for sensitive reviews. See [Sharing Security](/docs/review-and-approve/sharing-security) for the detailed setup, download warning, and revocation controls.
Watermarking protects playback through the share link. It does not replace careful permission management.
### Disable a link
Disable a link to stop access without deleting it.
A disabled link shows no shared content. You can enable it again later if access needs to be restored.
Use this when a review is paused or temporarily closed.
### Delete a link
Delete a link when it should never be used again.
Deleting the link permanently stops access through that URL.
## Create multiple links
You can create multiple links for the same asset, folder, collection, or project.
Each link can have its own:
* Permissions
* Password
* Expiration date
* Watermark setting
* Metadata visibility
* Version access
For example:
* Give a client a comment-only review link.
* Give the editor a link that allows downloading.
* Give a delivery partner a separate link for final files.
Changing or deleting one link does not require changing the others.
## Manage existing links
**Manage link settings**
The sharing controls show the links created for an item.
From there, you can:
* Copy a link again.
* Review its permissions.
* Change what recipients can do.
* Add or update a password.
* Change the expiration date.
* Disable or enable the link.
* Delete the link.
Permission changes take effect for anyone using that link.
Review active links when a project ends, a freelancer finishes their work, or a client no longer needs access.
## Guest activity
Aspect records active guest actions such as comments, edits, and uploads.
This helps your team understand who contributed feedback or made a change.
An anonymous share link does not provide individual tracking for someone who only opens or watches the content. Do not use share links as proof that a specific person viewed a file.
If you need ongoing, authenticated collaboration, add the person as a workspace member instead of relying on an anonymous share link.
## Share a collection
Collections let you gather assets from different locations without moving the original files.
Use a collection when you want to share a curated group such as:
* A client review set
* A presentation
* Campaign selects
* Final deliverables
* Portfolio content
* Approved assets
Create the collection, add the assets, and generate one share link for the complete set.
Curate and share assets without changing their original locations.
## Embed shared media
Individual previewable assets can be [embedded on another website](/docs/share-and-present/embed-videos) using their share link.
Embeds are useful for:
* Portfolio pages
* Internal websites
* Client portals
* Presentation pages
* Published videos
Embedding displays the Aspect viewer inside the webpage.
Review the share link's permissions before publishing an embed. Anyone who can access the webpage may also be able to access the embedded content.
## Sharing archived projects
Archiving a project moves it to the **Archived** section on the workspace homepage. This keeps it out of the team's main project list while leaving project permissions and share links unchanged.
Guests can continue to use an active share link according to its permissions. Available browser features can include:
* Previews
* Comments
* Metadata
* Version review
* Downloads, when permitted
You can archive projects in either Active Storage or Cold Storage. Archiving leaves the storage tier unchanged. To remove guest access, disable or delete the share link. See [archiving a project](/docs/concepts/core-concepts#archiving-a-project).
## Remove access
### Remove a workspace member
Remove the person from the workspace when they no longer need an Aspect account.
Before removing them, check whether they own or manage any active projects or workflows.
### Remove project access
Keep the person in the workspace but remove their project role when they should no longer see a specific project.
### Revoke guest access
Disable or delete the relevant share link.
If different audiences received separate links, revoke only the link that should no longer work.
## Recommended permission settings
### Internal editor
* Workspace role: Member or Limited Member
* Project role: Editor
* Share-link access: Not required for normal project work
### Freelance collaborator
* Workspace role: Limited Member
* Project role: Editor or Commenter
* Access only to the required projects
### Client reviewer
* Workspace access: None
* Share-link access: View and comment
* Downloading: Off unless required
* Earlier versions: Only when needed
* Password or expiration: Recommended for sensitive work
### Delivery recipient
* Workspace access: None
* Share-link access: View and download
* Commenting: Optional
* Expiration: Recommended for temporary delivery links
### External contributor
* Workspace access: None
* Share-link access: Upload
* Organizing and metadata editing: Only when needed
* Expiration: Recommended
## Sharing best practices
* Use workspace access for ongoing collaborators.
* Use share links for clients and occasional reviewers.
* Use Limited Member for people who should only see selected projects.
* Give each person the lowest access level they need.
* Create separate links for different audiences.
* Check the contents of a folder, collection, or project before sharing it.
* Hide internal metadata from client links.
* Review whether earlier versions should be visible.
* Leave downloading off for review-only links.
* Add passwords and expiration dates to sensitive links.
* Use watermarked playback for sensitive reviews, and turn off **Downloads** separately when recipients should not receive the original file.
* Disable or delete links when a project ends.
* Review project access when a teammate or freelancer changes roles.
* Do not rely on anonymous links to track passive viewing.
## Related guides
Collect precise feedback from teammates and external reviewers.
Share revisions while preserving feedback from each review round.
Curate assets from different locations and share them with one link.
Preview media, inspect transcripts, and review creative work.
# Watermarking
Source: https://aspect.inc/docs/share-and-present/watermarking
Protect shared video playback with a visible, configurable watermark.
Watermarking allows you to protect shared content by placing a visible identifier over video during playback.
Aspect applies the watermark through the share link. The original file remains unchanged.
## Create a watermark
You can create a watermark in two places.
### While creating a share link
Use this option when you need a new watermark for the link you are configuring.
Select the video or other resource, open **Share**, and select **Create share link**.
Under **Security**, open the **Watermark** menu.
Select **Create watermark**, configure the settings, and save it.
Select the new watermark before creating the share link.
### From Content Security settings
Use this option to create reusable watermarks before you configure a share link.
Open **Settings** for your Aspect workspace.
Under **Workspace**, select **Content Security**.
In **Watermarks**, select **Create watermark**, configure the settings, and save it.
When creating or updating a share link, select the saved watermark from the **Watermark** menu under **Security**.
## Configure the watermark
Each watermark includes the following settings.
### Name
Enter an internal name that helps your team recognize the watermark, such as "External Review" or "Client Preview".
### Text pattern
Build the text that appears over the video. Enter your own text and use the insert controls to add:
* **Email**
* **Name**
* **Time**
* **Workspace**
Arrange the fields and line breaks in the order you want them to appear.
Viewer information depends on the context available through the share link. Do not treat a watermark as proof that a specific person watched the video.
### Position
Choose one of nine preset positions, enter precise **X** and **Y** percentages, or click and drag the watermark in the preview.
### Appearance
Adjust how the watermark looks:
* **Color** sets the text color using a hex value.
* **Opacity** controls how transparent the watermark is.
* **Rotation** changes the text angle in degrees.
* **Size** offers small, medium, and large options.
* **Weight** offers light, normal, and bold text.
Use the preview to confirm that the watermark remains visible without covering important content.
## Apply or change a watermark
A watermark is selected separately for each share link.
When creating or updating a link:
1. Open the link's settings.
2. Find **Watermark** under **Security**.
3. Select a saved watermark or create a new one.
4. Save or create the link.
5. Test the link in a private browser window.
To remove the watermark, return to the link's settings and select **None**.
Watermarking does not turn off **Downloads**. If recipients should not receive the source file, review the link's **Downloads** permission separately.
## What watermarking does and does not do
A watermark provides a visible playback identifier and can discourage unauthorized sharing. It does not prevent screenshots, screen recordings, or other forms of copying.
Watermarking applies to playback through the protected share link. It does not permanently alter the original asset.
## Best practices
* Use a clear internal name for each watermark.
* Include only the viewer or workspace information needed for the review.
* Keep the watermark visible without blocking important details.
* Review **Downloads** separately.
* Test the completed share link as an external visitor.
* Create separate links when audiences need different security settings.
## Related guides
Protect links with passwords, expiration dates, permissions, and watermarks.
Understand workspace, project, and share-link access.
# Avid Media Composer
Source: https://aspect.inc/docs/workflows/avid-media-composer
Keep original media and Avid project files on Aspect, use Mimiq to enable NEXIS-style storage, and pin the media you are editing.
Keep your production's original media, Avid project files, bins, and exports in one Aspect project. Mount that project on each editor's computer, then use Mimiq to make the mounted drive appear to Media Composer as shared Avid NEXIS storage.
You can open and save the Avid project directly on the mounted drive, pin the footage you are working with for local playback, and share the same media with your team. Teams using bin locking can work in different bins within the same Avid project.
## Before you start
| You need | What to check |
| - | - |
| **Aspect desktop app** | Install [Aspect for macOS or Windows](/docs/apps/desktop), sign in, and use an **Active Storage** project. |
| **Project access** | Each editor needs read and write access to the project, including its root, so Avid can create its media folders. |
| **Avid Media Composer** | Hedge requires **Media Composer Ultimate or higher**, or a **perpetual license**. Check the [Mimiq requirements](https://docs.hedge.video/mimiq/requirements) for supported versions. |
| **Mimiq Pro, 30-day license** | Use Hedge's [30-day Mimiq Pro rental](https://account.hedge.co/store/8856/licenses?pro=true\&type=project\&validity=30). Have an activation available for each editing computer. |
| **A fast local cache drive** | Use an SSD or NVMe drive with room for your cache and the full size of the media you plan to pin. |
The 30-day Mimiq license is a paid rental, separate from Hedge's free trial. Keep it active for the duration of your edit. Use a combination of Media Composer, Mimiq, and operating system versions listed in [Hedge's compatibility requirements](https://docs.hedge.video/mimiq/requirements).
## 1. Put your original media on Aspect
Create an Aspect project using **Active Storage**, then upload the original camera media, production audio, graphics, and other source material. Keep camera-card folder structures intact when the format depends on accompanying files.
Use folders such as **Raw Media**, **Avid Projects**, and **Exports** to separate source footage from editorial work. Invite your editors to the Aspect project with the access they need.
An **Aspect project** is the shared storage you mount. An **Avid project** is the project folder you will create inside that storage. One does not replace the other.
Put the originals on Aspect even if you plan to edit with Avid-generated proxies. Your team can keep both the source media and the editorial media together throughout the production.
## 2. Mount the Aspect project
In the Aspect desktop app, select the **drive icon** in the left sidebar.
Find the project and select **Mount**. Mount the project itself for this workflow so Avid has access to the drive root.
Reveal the mounted path in Finder or File Explorer. Confirm that you can see your uploaded media and create a folder at the root.
On macOS, the path may look like `/Volumes/Example Film`. On Windows, use the drive letter shown by Aspect, such as `Z:`.
Keep the project name and mounted path consistent during the edit. On each workstation, check the actual path before opening Avid; a different drive letter or a renamed volume can require relinking source media. Do not assume that Windows assigns the same drive letter on every computer.
See [Mount your first project](/docs/instant-access/mount-a-project) for the full mounting walkthrough.
## 3. Install and activate Mimiq
Mimiq lets Media Composer recognize eligible third-party storage as Avid NEXIS storage. Aspect continues to handle the mounted files, streaming, caching, and synchronization.
Complete the storage setup before launching Avid.
Download the installer for [macOS](https://hedge.video/download/mimiq/macos) or [Windows](https://hedge.video/download/mimiq/windows), run it, and complete any installation prompts.
Launch Mimiq and activate it with your Mimiq Pro license key. Confirm that the license is active on this computer.
With your Aspect project mounted, open Mimiq from the menu bar on macOS or the system tray on Windows.
Find the mounted Aspect volume and confirm that it shows a **green status**. If it is missing or not green, check the mount, read and write permissions, license, and version compatibility before continuing.
For each editing session, use this order: **mount Aspect → launch Mimiq → launch Media Composer**.
## 4. Confirm that Avid sees NEXIS storage
Launch Media Composer with the Aspect project mounted and Mimiq running. If Avid displays a prompt about third-party storage emulating Avid NEXIS, choose **Yes**.
Check that your mounted Aspect volume appears under **Avid NEXIS Drives**:
Open **Avid Media Composer → About Avid Media Composer → Hardware → Avid NEXIS Drives**.
Open **Help → About Avid Media Composer → Hardware → Avid NEXIS Drives**.
On versions that expose it, check **Settings → Project → General → Enable Bin Sharing on 3rd party storage emulating Avid NEXIS/ISIS**. Current Mimiq versions may handle this without a separate manual step; follow [Hedge's setup instructions](https://docs.hedge.video/mimiq/getting-started#confirm-bin-locking-is-activated-in-avid-media-composer) for your version.
Seeing the drive in Finder or File Explorer confirms that Aspect is mounted. Seeing it under **Avid NEXIS Drives** confirms that Media Composer recognizes the emulated shared storage. Check both before putting an active Avid project on the drive.
## 5. Create or move your Avid project onto Aspect
In Media Composer's project selection window, choose the mounted Aspect drive as your project location. Depending on your Avid version, use the **External** location or browse to the drive.
Create the Avid project inside **Avid Projects**, for example `Avid Projects/Example Film`. Set **Search data folder** to **Local default** so Avid's search index stays on the workstation.
For an existing project, close it on every workstation first. Copy the **complete Avid project folder** into `Avid Projects`, wait for Aspect to finish uploading it, then open the project from that mounted location. Keep your existing copy as a backup during the move.
The project folder contains the `.avp` project file, `.avb` bin files, and associated settings. Bins hold your clips and sequences; moving only the `.avp` file does not bring the bins or source media with it.
As you work, your mounted project might look like this:
```text theme={null}
Example Film/ ← Mounted Aspect project
├── Raw Media/
│ ├── Camera A/
│ └── Production Audio/
├── Avid Projects/
│ └── Example Film/
│ ├── Example Film.avp
│ ├── Interviews.avb
│ └── Sequences.avb
├── Avid MediaFiles/ ← Created and managed by Avid
│ └── MXF/
│ ├── EDITOR-A.1/
│ └── EDITOR-B.1/
└── Exports/
```
The tree shows the main files; keep Avid's additional settings and support files with the project. Let Avid manage the contents of **Avid MediaFiles**.
### Set the media destination
Open **Settings → Media Creation** and select the mounted Aspect **drive** for the media you want to share, including imports, transcodes, and shared renders.
Avid creates its managed media structure at the drive root. For MXF media on emulated shared storage, that is typically `Avid MediaFiles/MXF/ComputerName.1`. Give each workstation a unique computer name so Avid can use separate media folders.
Keep `Avid MediaFiles` at the root, with its exact name. Do not place it inside `Raw Media` or `Avid Projects`, and do not mix a local-disk numbered-folder layout with Avid's shared-storage layout on the same volume.
## 6. Link media and pin your working files
Use Avid's **Source Browser** to browse to **Raw Media** on the mounted Aspect project and link the footage into a bin. Install any source-format plug-ins required by your camera media.
For formats or sequences that need lighter editorial media, use **Consolidate/Transcode** in Avid and choose the mounted Aspect drive as the destination. Select an appropriate DNxHD or DNxHR resolution for the project; DNxHR LB is one option for a lightweight offline edit. Avid writes these files into its managed media folders.
Pin the files you will actually play in the edit:
1. In the Aspect desktop app, select the original media, Avid-generated media, audio, and graphics needed for your current sequence.
2. Choose **Pin** for those files or folders.
3. Keep Aspect running until pinning finishes, then open the sequence and check playback.
If your timeline uses transcoded MXF media, pin that media as well as any linked originals it still uses. Pinning the `.avp` and `.avb` files alone does not pin their referenced footage.
Pin the current episode, scene, or day's footage instead of the entire production. The originals stay on Aspect, while your working media is available on the local cache drive. Continue opening it through the mounted path.
Pinning downloads complete files and keeps them locally. It does not transcode the media or create a separate editorial copy. Each editor chooses what to pin on their own computer. See [Pinning](/docs/instant-access/pin-files) for more detail.
## 7. Collaborate with your team
Have each editor mount the same Aspect project. Choose a shared Avid project with verified bin locking, or use the handoff workflow below. Keep Aspect and Mimiq running while editing, and allow saved changes to finish synchronizing before handing work to another editor.
### If your team uses bin locking
Bin locking gives one editor write access to a bin while others can read it. Editors can work in different bins at the same time. It does not merge two people's changes to the same bin.
Each participating workstation needs the appropriate Avid license, an active Mimiq setup, and read and write access to the shared project. Before starting a shared edit, verify locking between **two computers** using a test bin:
1. Editor A opens the bin and confirms that they hold the lock.
2. Editor B opens the same bin and confirms that it is read-only and identifies Editor A's computer as the owner.
3. Editor A saves and closes the bin, then waits for Aspect to finish synchronizing.
4. Editor B refreshes the bin or project and acquires write access. Confirm that the latest changes are present before editing.
Mimiq documents these Avid lock states:
| Lock color | Meaning |
| - | - |
| **Green** | You hold the lock and can save changes. |
| **Red** | Another editor holds the lock; you have read-only access. |
| **Yellow** | The other editor has updated the bin. Click the padlock to refresh it. |
| **Blue** | The previous owner released the bin. Click the padlock to acquire write access. |
Save and close bins when you finish with them. For a handoff, the receiving editor should refresh and confirm ownership before making changes. Avoid renaming or moving bins while teammates have them open.
If both computers can write to the test bin, stop simultaneous editing and check the setup. A green volume in Mimiq or locally pinned files does not, by itself, verify bin locking between teammates. Stay online during a shared edit so saves and lock changes can synchronize.
### If your team does not use bin locking
You can still share the original media and collaborate through planned handoffs. Keep one editor responsible for an Avid project at a time, or give each editor a separate Avid project folder and exchange closed bins when needed.
For a handoff, the outgoing editor saves and closes the project, waits for synchronization to finish, and tells the next editor it is ready. The next editor confirms that the latest files have arrived before opening the project.
Pinning improves access to the media; it does not reserve a project or bin for you. Arrange exclusive ownership before working offline on any shared project files.
## Make playback more reliable
Start with the network and the local drive that holds Aspect's cache:
* **Use Ethernet.** A wired connection gives more consistent results than Wi-Fi for streaming media and synchronizing work.
* **Use a fast SSD or NVMe cache drive.** For an external drive, use a fast connection such as Thunderbolt and keep it connected throughout the session.
* **Use the right filesystem.** Choose APFS for a Mac cache drive or NTFS for Windows. Avoid exFAT for an active editing cache.
* **Allow enough space.** A 50–200 GB automatic cache is a useful starting point if disk space allows. Budget for the full size of pinned media as well, plus Avid's caches, renders, and operating-system free space. A large edit may need substantially more.
* **Keep the workstation awake.** Prevent sleep or disk disconnection during pinning, playback, renders, and uploads.
Configure the cache through [Aspect's cache settings](/docs/instant-access/manage-cache). Keep that local cache on the workstation or attached drive, outside the mounted Aspect project.
### Match the media to your connection
For media that is not pinned, consider the combined bitrate of all streams playing at once, including multicam angles. Leave headroom for audio, other users, uploads, and network variation.
For example, four 100 Mbps video streams need about 400 Mbps before overhead. A connection advertised as 500 Mbps may leave little margin. Pin the working media ahead of time or use lower-bitrate Avid editorial media when streaming cannot keep up.
### Tune Media Composer
| Setting | Recommendation |
| - | - |
| **Search data folder** | Use **Local default** when creating the project. |
| **Settings → User → Timeline → Use Fast Scrub** | Disable it if scrubbing produces stalls or playback timeouts. Hedge recommends disabling it for shared-storage work. |
| **Settings → Site → Media Cache → Video Memory** | Increase the allocation gradually if RAM is available, then test playback. This is separate from Aspect's disk cache. |
| **Bin and phonetic indexing** | If indexing is consuming resources during an edit, temporarily pause it through the Find window's search options. Resume it afterward and leave Avid open to finish; search, PhraseFind, and ScriptSync depend on the index. |
Use [Avid's system requirements](https://kb.avid.com/pkb/articles/en_US/Knowledge/Media-Composer-System-Requirements) and [computer optimization guides](https://kb.avid.com/pkb/articles/en_US/Knowledge/en367983) for settings specific to your workstation and Avid version.
## Finish the session
Export review files to **Exports** in the mounted Aspect project, then save your bins and close the Avid project. Wait for Aspect to finish synchronizing before quitting the desktop app, unmounting, or disconnecting the cache drive.
Your team can open the updated project after the handoff, or use Aspect's [sharing and review tools](/docs/share-and-present/sharing-and-permissions) to send the export for feedback.
## Troubleshooting
Quit Avid. Confirm that the project is mounted in Aspect, then check that Mimiq lists the volume with a green status and an active license. Relaunch Mimiq if the mount was added after it started, then launch Avid again.
Check read and write access at the drive root and the supported Avid/Mimiq version combination. If the volume still does not appear, contact Aspect support with your OS, Aspect, Mimiq, and Media Composer versions. Complete this check before moving an active project onto the drive.
Confirm that the same Aspect project is mounted at the expected path, uploads have finished, and the files can be opened from the mounted drive. Linked source files may need relinking if their path changed.
For Avid-managed media, check that `Avid MediaFiles` is at the drive root and that Avid's shared-storage folder structure is intact. Allow media creation, uploads, and Avid's media database scan to finish. Avoid moving or renaming Avid-managed media folders to fix the problem.
Confirm that both editors opened the same project and bin from the same Aspect project. Check synchronization status, keep both workstations online, and refresh the bin or project in Avid.
Repeat the two-computer lock check. Use a single-editor handoff until ownership and refresh work as expected; do not delete lock files while another editor may be working.
Confirm that pinning has finished for the files the sequence actually uses, including transcoded media. Check cache-drive speed, connection, free space, codec requirements, and Avid's memory and playback settings. Pinning removes the need to stream those files, but decoding and effects still depend on the workstation.
## Related guides
Set up the Aspect drive and check synchronization.
Keep the media for your current edit available locally.
Check installation, volume recognition, and Avid settings.
Understand lock ownership and bin refresh.
# Caching
Source: https://aspect.inc/docs/workflows/caching
Prepare Aspect's local cache for a responsive editing session and manage it as your working set changes.
Aspect caches the file segments your applications request from a mounted project. Frequently used content stays local for faster repeat access, while the project remains stored and synchronized in Aspect.
Caching happens automatically. Use this workflow to choose an appropriate location and limit, prepare active media, and decide when pinning is the better option.
## Prepare the cache
Open the Aspect desktop app settings and find the local cache controls.
Confirm that the cache is stored at a location with enough available space. You can use your primary disk or [an external SSD](/docs/workflows/external-drive).
Set the maximum space Aspect may use. Leave room for your operating system, creative applications, project files, and exports.
Mount the project and open it from your computer's file browser.
Open and scrub through a few files from the actual project in the application you plan to use. Aspect streams the requested segments and prefetches content it expects the application to need next.
Revisit the same media and test normal playback. Previously accessed segments can be read from the local cache instead of being streamed again.
## During the session
* Keep the cache location available while you work.
* Let Aspect manage the contents of the cache folder.
* Monitor available local storage during long or media-heavy sessions.
* Increase the limit if active footage is repeatedly being streamed again.
* Reduce the limit when you need to recover local space.
When the cache approaches its configured limit, Aspect removes older cached segments to make room for recently accessed content. This does not delete or change the original files in Aspect.
Change the cache limit or location and troubleshoot cache performance.
## Know when to pin
A cache improves connected work, but it does not guarantee that a complete file is stored locally.
| Cache | Pinning |
| - | - |
| Stores accessed file segments automatically | Downloads the complete file or folder |
| May remove older content automatically | Keeps content local until you unpin it |
| Supports normal connected work | Supports offline or guaranteed local access |
| Uses the configured cache limit | Requires space for the complete pinned content |
Before traveling or working with an unreliable connection, [pin everything you need](/docs/instant-access/pin-files) and wait for pinning to finish.
## Use an office shared cache
Some organizations use an Aspect-managed on-site shared cache. After one person retrieves content, other workstations on the same local network may reuse it at local-network speed instead of downloading it separately.
Shared-cache availability depends on your workspace and deployment. Contact Aspect to confirm whether it is available for your organization.
## Troubleshoot the workflow
If previously accessed media begins streaming again:
* Confirm that the configured cache location is still available.
* Check whether the cache limit was reduced.
* Check whether older content was automatically evicted.
* Confirm that the cache drive has free space.
* Make sure the Aspect desktop app is running.
* Check the internet connection for content that is not cached.
If playback remains inconsistent, follow the performance guidance in [Understanding how Instant Access works](/docs/instant-access/overview).
## Related guides
Move Aspect's local cache to an external SSD.
Control the cache size and storage location.
Keep complete files and folders available offline.
Learn how streaming, prefetching, caching, and synchronization work together.
# DaVinci Resolve
Source: https://aspect.inc/docs/workflows/davinci-resolve
Share original footage on Aspect, collaborate through Blackmagic Cloud or DRP handoffs, and use proxies and pinning for your current timeline.
Keep all the original footage on Aspect so editors, colorists, and finishing artists can work from the same source files. Each teammate mounts the same Aspect project and imports media from that shared root.
With consistent mounted paths and filenames, the next person can open the project against the same media without relinking it for every handoff.
## Connect Resolve to Aspect
1. Upload your original footage, audio, and graphics to an **Active Storage** project and give your team access.
2. Open the [Aspect desktop app for macOS or Windows](/docs/apps/desktop) and **Mount** that project from the drive view.
3. In Resolve's Media page, browse to the mounted drive and add your media to the Media Pool. If the drive is not listed, add its path under **Preferences → System → Media Storage**.
Mount the whole Aspect project at the same root on each workstation. Keep Mac volume names and Windows drive letters consistent. For mixed Mac and Windows teams, configure Resolve's **Mapped Mount** paths so each workstation resolves the shared media correctly.
See [Mount your first project](/docs/instant-access/mount-a-project) for the Aspect setup.
## Choose how to share the Resolve project
Resolve keeps active projects in a **project library**. Keep that library local or use Blackmagic Cloud; store the shared footage and exported `.drp` files on Aspect.
### Work together with Blackmagic Cloud
In Resolve's Project Manager, sign in to Blackmagic Cloud, create or open a project in a Cloud project library, and invite your collaborators. Use Resolve's collaboration controls to work together.
Import the project's media from the mounted Aspect drive. Blackmagic Cloud manages the shared project, while Aspect gives each editor access to the same originals and proxies.
### Hand off a DRP file through Aspect
If your team is not using Blackmagic Cloud, pass the project through Aspect when another person needs to pick up the edit:
Save your work, open Resolve's **Project Manager**, right-click the project, and choose **Export Project**.
Choose a location on the mounted Aspect project and save the `.drp` file. Use a clear version name and wait for Aspect to finish synchronizing it.
The next editor mounts the same Aspect project, opens **Project Manager**, and chooses **Import Project** to import the `.drp` into their project library.
They open the imported project and confirm that the timeline resolves to the shared media.
After editing, export a new `.drp` back to Aspect. Coordinate who owns the next version before someone else continues.
A `.drp` is a snapshot of the project, including its timelines, grades, and settings. It does not include the source media or update itself as you edit. Export a fresh `.drp` for each handoff; importing it does not create a live collaborative project.
## Use proxies for the edit
Keep the raw footage on Aspect even when editing with lighter proxies. Use the originals for color decisions and full-quality finishing.
### Copy existing Aspect proxies
1. In Aspect, select the source videos or a folder and choose **Copy**.
2. Choose a destination in the shared Aspect project.
3. Enable **Copy videos as proxies** under **Content**, then select **Copy**.
4. Wait for the MP4 copies to finish. Videos still processing are copied once their proxies are ready; the originals remain in place.
In Resolve's Media Pool, select the original clips, right-click, and choose **Link Proxy Media**. Locate the corresponding copied proxies on the mounted drive and confirm that Resolve matches them.
Resolve checks properties such as timecode and frame rate when linking proxies. If a copied proxy cannot be matched, generate one from the original in Resolve.
### Generate proxies in Resolve
Choose the proxy format and resolution in **Project Settings**, then select the clips in the Media Pool, right-click, and choose **Generate Proxy Media**. Set the proxy generation location to the mounted Aspect project when the team should share those files.
Use **Playback → Proxy Handling → Prefer Proxies** while editing. Check picture and audio on several clips, then switch to **Prefer Camera Originals** for finishing with the source media.
## Keep the cache local
In **Project Settings → Master Settings → Working Folders**, set **Cache files location** to a fast local SSD. Resolve's generated cache is separate from [Aspect's cache](/docs/instant-access/manage-cache).
Pin high-bitrate media before a grading or finishing session when your connection cannot sustain playback. Streaming performance also depends on the number of simultaneous streams, the codec, and the workstation's decoding capacity.
## Pin the current timeline for offline work
Select and **Pin** the actual footage, audio, graphics, and linked proxies used by your timeline in Aspect. Wait for pinning to finish and check that the timeline plays from the mounted drive.
A pinned `.drp` does not contain or pin the footage. Pin the proxies for an offline edit, and the camera originals if you need them for grading or full-quality output.
Before leaving a Blackmagic Cloud project offline, export a `.drp` and prepare a local project for the session. Agree with the team on how that work will be handed back. Local changes will not merge into the shared Cloud project simply because the media is pinned.
After reconnecting, allow new media and project exports to finish synchronizing before the next person picks them up.
Keep the files for your current timeline available locally.
Configure Aspect's local cache for your media.
# Working off an external drive
Source: https://aspect.inc/docs/workflows/external-drive
Use an external SSD for Aspect's local cache while keeping your project files in Aspect.
Use an external drive when you want more room for streamed media without filling your computer's primary disk.
The external drive stores Aspect's **local cache**. Your project remains in Aspect as the shared source of truth. Files still stream on demand, changes synchronize back to the project, and removing cached data does not delete the originals.
## When to use this workflow
An external cache drive is useful when:
* Your primary disk has limited free space.
* You repeatedly work with large media files.
On macOS, use an APFS-formatted external drive when possible. Aspect does not currently publish a recommended filesystem for every operating system.
## Set up the external drive
Connect the external SSD and confirm that it appears in your computer's file browser. Make sure you can create and save a test file on it.
Open the Aspect desktop app settings and find the local cache controls.
Change the cache location to a folder on the external drive. Use a dedicated folder so the Aspect cache is easy to identify.
Choose the maximum space Aspect may use. Leave room for other files on the drive instead of assigning its full capacity to the cache.
Mount the Aspect project and open media from the mounted drive in your creative application. Aspect streams the requested content and stores recently accessed segments in the external cache.
Cache data may contain only parts of a file and may be removed automatically. [Pin files or folders](/docs/instant-access/pin-files) when you need complete, guaranteed local copies.
## During the work session
* Keep the selected cache drive connected and available.
* Save work to the mounted Aspect project, not inside the cache folder.
* Confirm that changes have synchronized before ending the session.
* Keep enough free space for the cache, project files, and exports.
* Expect the first access to uncached content to use your internet connection.
Do not use the cache folder as a backup or manually organize files inside it. Aspect manages that folder automatically, and the originals remain in the Aspect project.
## Cache or pin?
| Use the cache when | Pin content when |
| - | - |
| You are working online | You need to work without a reliable connection |
| You want faster repeat access | You need a complete file or folder stored locally |
| Aspect can manage older local data automatically | The content must remain local until you unpin it |
## Troubleshoot the external cache
If Aspect cannot use the selected location:
* Confirm that the drive is connected and visible to the computer.
* Confirm that you can write to the selected folder.
* Check that the drive has available space.
* Reopen the Aspect desktop app and review the configured cache location.
* Choose another supported location if the external drive will not be available for the session.
For general streaming or mounting issues, review [Mount your first project](/docs/instant-access/mount-a-project) and [Understanding how Instant Access works](/docs/instant-access/overview).
## Related guides
Prepare and manage the cache for an active work session.
Change the cache size or location and understand automatic eviction.
Keep complete files and folders available offline.
Connect an Aspect project to your computer and open it as a mounted drive.
# Final Cut Pro
Source: https://aspect.inc/docs/workflows/final-cut-pro
Keep shared originals on Aspect, understand Final Cut's file references, and use proxies and pinning when editing or handing off a library.
The Aspect desktop app supports **macOS and Windows**. This workflow uses macOS because the desktop version of Final Cut Pro runs on Mac.
Store your original footage on Aspect so everyone on the team can access the same files. Mount the Aspect project on each Mac, then let Final Cut Pro reference that media from your library.
Using the same mounted root keeps those references consistent when a library moves between editors, so you do not have to relink the footage at each handoff.
## Mount the project and open a library
1. Upload your raw footage, audio, and graphics to an **Active Storage** project and give your editors access.
2. In the Aspect desktop app, open the drive view and select **Mount**. Confirm that the project appears in Finder.
3. In Final Cut Pro, choose **File → New → Library** and save the library on the mounted Aspect project, or open an existing library from that drive.
Keep the entire `.fcpbundle` library together. Use one editor at a time for a shared library; separate libraries can reference the same raw footage for parallel work.
Have every Mac mount the whole Aspect project under the same volume name. Import from that mounted root, rather than from an editor's Downloads folder or a separate local copy.
## Choose how Final Cut references your media
For originals already stored on Aspect, use **Leave files in place** in Final Cut's import settings.
| Import option | What happens |
| - | - |
| **Leave files in place** | The library contains references to the original files at their existing locations. It does not copy the footage into the library. |
| **Copy to library storage location** | Final Cut duplicates the files into the library's configured Media location. With Media set to **In Library**, those copies are stored inside the library bundle. |
### How symlinks work
With **Leave files in place**, Final Cut creates **symbolic links**, or **symlinks**: small files inside the library that point to the source media. Opening a clip follows that reference to the footage on the mounted Aspect project.
The link is not a copy of the video. Copying or handing off the library carries the reference, while the original media stays where it is. This lets multiple libraries use the same shared originals without duplicating the camera files into each library.
For those links to work on another Mac:
* The original files must be on Aspect and accessible to that editor.
* The same Aspect project must be mounted at the same root path.
* Media names and locations must remain consistent during the edit.
A reference to a file on one editor's Desktop will not make that file available to the team. Put the media on Aspect before importing it. If a referenced file has moved, use **File → Relink Files → Original Media** to reconnect it.
If you need a library containing actual media copies, set its Media location to **In Library** and consolidate the required media through Final Cut. Changing the storage setting alone does not move previously imported files. See [Apple's explanation of import references](https://support.apple.com/guide/final-cut-pro/organize-files-during-import-ver392f50c2/mac).
## Set import and cache preferences
Open **Final Cut Pro → Settings → Import**; older versions call this **Preferences**.
* Choose **Leave files in place** for the media already on Aspect.
* Turn off automatic **Analyze Video** options such as **Balance color** and **Find people**.
* Turn off automatic **Analyze Audio** options such as **Fix audio problems** when they are not needed for the import.
* Leave **Create optimized media** and **Create proxy media** off for bulk imports. Generate the representations you need for selected clips afterward.
These settings also apply when you drag media into Final Cut from Finder. For a one-off import, review the same options in **File → Import → Media**. Pin selected clips before running analysis or transcoding when you want the work to read from local storage.
For cache files, select the library and open **File → Library Properties → Modify Settings**. Set **Cache** to a fast local SSD. The cache holds generated render, analysis, thumbnail, and waveform files; it is separate from your shared originals and [Aspect's cache](/docs/instant-access/manage-cache).
## Work with proxies
Use proxies for lighter playback while keeping the originals on Aspect for finishing.
### Reuse proxies from Aspect
1. In Aspect, select the source videos or a folder and choose **Copy**.
2. Choose a destination in the shared Aspect project.
3. Enable **Copy videos as proxies** under **Content**, then select **Copy**.
4. Wait for the MP4 copies to finish. Videos still processing are copied once their proxies are ready; the source originals stay in place.
Select the original clips in Final Cut, then choose **File → Relink Files → Proxy Media**. Locate the corresponding copied MP4s, review the matches, and complete the relink.
Final Cut requires compatible media duration, frame rate, and audio channels. If a copied proxy does not match, create the proxy in Final Cut instead.
### Create proxies in Final Cut
Select the clips you need, choose **File → Transcode Media**, and enable **Create proxy media**. Choose **ProRes Proxy** or **H.264** and an appropriate frame size.
Final Cut stores generated proxies in the library's configured **Media** location. To share them, use **In Library** when the library is on Aspect, or choose another media location on the mounted Aspect project through **Library Properties → Modify Settings**.
In the viewer's **View** menu, choose **Proxy Preferred** for playback. Use **Proxy Only** when checking that every clip needed for an offline edit has a proxy. Switch back to **Optimized/Original** before a full-quality export and confirm that the required media is available.
## Pin the library and timeline media
Before going offline, pin the library and the actual files used by your timeline in Aspect:
* Pin the `.fcpbundle` library you will edit.
* Pin the original or proxy video files you will play, plus audio and graphics.
* Wait for pinning to finish, then open the library and check the timeline in the intended playback mode.
With externally referenced media, the library's symlinks are not the footage. Include their target files in your pinning selection. Pin camera originals too if you need them for finishing or exporting while offline.
Continue working through the mounted Aspect path so the library keeps the same references.
## Hand the library to another editor
Finish your edit and close the library in Final Cut. Wait for Aspect to finish synchronizing the library and any newly generated media, then let the next editor know it is ready.
The next editor mounts the same Aspect project, confirms the latest files are available, and opens the library. Keep one owner of a shared library at a time, including during offline work; Aspect does not merge simultaneous edits to a Final Cut library.
Make the shared media available at a consistent mounted path.
Keep the library and its referenced media available locally.
# Metadata
Source: https://aspect.inc/docs/workflows/metadata
Use automatic technical details and project-specific custom fields to organize, filter, search, and share assets.
Every asset in Aspect carries metadata: information about the file itself and information your team adds to support its workflow.
Aspect extracts technical details automatically. You can add custom fields for project-specific information such as status, campaign, category, rights, or QA.
## Automatic technical metadata
When you upload a file, Aspect reads the technical metadata embedded in it. Depending on the file type, this can include:
* Resolution
* Duration
* Codec
* Frame rate
* Camera information
* GPS location, when the file contains it
* EXIF and IPTC data, when available
Open an asset and use its details panel to review the metadata Aspect extracted. Extraction happens automatically as part of processing a new upload.
## Custom metadata fields
Custom fields let your team track information that is specific to a project or workflow.
Fields are defined at the project level, so each project can use its own structure. Common examples include:
* Approval or QA status
* Campaign or client name
* Usage rights
## Supported field types
Choose the field type that matches the information you want to store:
* **Text:** Names, notes, identifiers, or other free-form information.
* **Number:** Ratings, counts, version numbers, or other numeric values.
* **Date:** Shoot dates, deadlines, air dates, or expiration dates.
* **Checkbox:** Yes-or-no values such as Approved or Cleared.
* **Single select:** One value from a defined list, such as a production status.
* **Multi select:** Multiple values from a defined list, such as categories or tags.
Single-select and multi-select fields can use colored options, making values easier to scan in the library.
## Create a custom field
1. Open **Settings**.
2. Select the project you want to configure.
3. Open **Metadata**.
4. Add a field name and choose its type.
5. For a single-select or multi-select field, add the available options and choose their colors.
6. Save the field.
The new field is available for assets in that project.
Changing or removing a field can affect every asset that uses it. Confirm the field name, type, and options before applying a structural change.
## Add or update metadata values
Open an asset and use the metadata controls in its details panel to add or change values.
For bulk work, select the relevant assets before applying the value, or use Aspect Agent to update many assets as one workflow.
Useful values are consistent and specific. For example, use the same status options across a project instead of entering several variations of the same term.
## Filter and search with metadata
Metadata can help narrow a large project before you browse or search.
Use filters to find assets based on technical or custom metadata, such as:
* Videos with a specific resolution or frame rate
* Assets marked Approved
* Files associated with a campaign
You can combine metadata filters with [AI Search](/docs/asset-intelligence/ai-search). This lets you match what an asset contains and the structured information your team has added.
For example, search for an interview quote while limiting the results to assets whose Status field is Approved.
## Use Aspect Agent for bulk metadata work
Aspect Agent can create custom fields and update values across multiple assets.
Try requests such as:
* `Create a QA field with Not started, In progress, and Complete options.`
* `Mark everything in the Interviews folder as Complete for QA.`
* `Set the Campaign field to Spring Launch for these assets.`
For changes that affect your library, review the selected assets and proposed values before approving the action.
Find, organize, and update project content with Aspect Agent.
## Populate fields automatically
Custom fields can use written guidance to populate values from asset content as files are uploaded.
Define the field and the values you want Aspect to recognize, then provide clear guidance or examples. This is useful for project-specific taxonomy such as content category, product, campaign, location, or QA status.
Review automatically added values as part of your normal ingest or QA workflow.
## Metadata on share links
Share-link settings can control whether people using the link can view or edit metadata.
Before sharing, review which metadata fields are visible. Keep internal information such as budgets, rights notes, or production details hidden when recipients do not need it.
Configure access, metadata visibility, and other controls for share links.
## Metadata in archived projects
Archiving a project moves it to the **Archived** section on the workspace homepage. Its assets retain their metadata, previews, search access, and sharing behavior.
You can archive projects in either Active Storage or Cold Storage. Archiving leaves their storage tier unchanged, and you can continue to find and update metadata according to your permissions. See [archiving a project](/docs/concepts/core-concepts#archiving-a-project).
## Metadata best practices
* Use field names that are clear to everyone working in the project.
* Keep select options short and mutually exclusive when possible.
* Use single select for one status and multi select for several applicable categories.
* Agree on a small set of values before applying metadata in bulk.
* Review automated values during ingest or QA.
* Avoid exposing internal fields on external share links.
* Keep metadata attached to the source asset instead of repeating the same information in filenames.
## Related guides
Create fields and update metadata across multiple assets.
Choose which metadata appears in the project library.
Control access and metadata visibility on share links.
# Premiere Pro
Source: https://aspect.inc/docs/workflows/premiere-pro
Edit shared media from Aspect in Premiere Pro using individual projects, Productions, or Team Projects, with proxies and offline pinning.
Keep your original footage on Aspect so every editor works from the same media. Mount the project on each computer, import from the mounted drive, and use the Premiere collaboration workflow that fits your team.
When everyone uses the same mounted root and the media stays at the same paths, you can hand off projects without relinking the footage each time.
## Mount the shared media
1. Upload your original footage, audio, and graphics to an **Active Storage** project in Aspect. Give your editors access to that project.
2. In the [Aspect desktop app for macOS or Windows](/docs/apps/desktop), open the **drive view** and select **Mount** for the project.
3. Confirm that the drive appears in Finder or File Explorer, then import your media into Premiere from that mounted location.
Have everyone mount the whole Aspect project at the same root. Keep volume names consistent on Macs and check drive letters on Windows. For a team using both operating systems, establish the media mapping once rather than moving or duplicating the footage for each editor.
See [Mount your first project](/docs/instant-access/mount-a-project) for the full setup.
## Choose your Premiere workflow
### Individual projects
Save the `.prproj` file on the mounted Aspect project and import the shared media from that drive. This works well for one editor or a project passed between editors.
Enable **Project Locking** in Premiere's **Collaboration** settings and set your username. Before sharing the project, confirm that a second editor sees it as read-only while the first editor has it open. To hand it over, save and close the project, wait for Aspect to finish synchronizing, then have the next editor open it.
### Productions
Create or open the Production on the mounted Aspect project. Keep the Production folder and its project files together on Aspect so the team sees the same set of projects.
Productions let editors work in different project files while project locking controls who can change each one. Enable locking and use a recognizable username on every workstation. Save and close a project when another editor needs write access, and allow synchronization to finish before the handoff.
### Team Projects
Create or open the Team Project through Adobe and invite your collaborators there. Import its source media from the mounted Aspect project.
Adobe manages the shared edit and its changes; Aspect provides the common media. Each editor mounts the same Aspect project and uses Team Projects' **Get Latest Changes** and **Share My Changes** controls as usual.
## Set up Premiere for mounted media
Open Premiere's **Settings** or **Preferences**; the menu name varies by version. Apply these settings on each workstation before importing a large amount of footage:
| Setting | Recommendation |
| - | - |
| **Audio → Automatic audio waveform generation** | Turn it off to avoid reading all imported audio just to build waveforms. Generate waveforms when you need them. |
| **Media Analysis & Transcription → Analyze all imported media to search for visuals or audio** | Turn it off so importing a large project does not trigger analysis of every file. |
| **Media Analysis & Transcription → Automatically transcribe clips** | Turn it off. Transcribe selected clips when needed. |
| **Collaboration → Enable Project Locking** | Turn it on for shared project files and Productions, and enter your username. |
| **Media Cache → Media Cache Files** | Choose a fast local SSD for Premiere's media cache. |
If you need analysis, transcription, or waveforms for a group of clips, [pin those files](/docs/instant-access/pin-files) first, then run the task. Premiere's media cache is separate from [Aspect's local cache](/docs/instant-access/manage-cache).
## Edit with proxies
Proxies reduce the amount of media your workstation needs to read and decode. Keep the originals on Aspect and attach proxies to the original clips so you can switch between them in Premiere.
### Copy proxies from media already on Aspect
1. In Aspect, select the source videos or a folder containing them and choose **Copy**.
2. Choose a destination in your shared Aspect project.
3. Under **Content**, enable **Copy videos as proxies**, then select **Copy**.
4. Wait for the copy to finish. Videos still processing will be copied when their proxies are ready.
Aspect creates smaller MP4 copies. The source originals remain in place; other file types are copied as-is.
In Premiere's Project panel, select the original clips, right-click, and choose **Proxy → Attach Proxies**. Locate the matching MP4 copies on the mounted Aspect drive and check the matches before attaching them.
### Create proxies in Premiere
Select the source clips in the Project panel, right-click, and choose **Proxy → Create Proxies**. Choose a proxy preset and a destination on the mounted Aspect project. Adobe Media Encoder creates the proxies and Premiere attaches them to the source clips.
Use this option when you need a particular editorial codec or an Aspect proxy does not match Premiere's frame-rate, duration, or audio-channel requirements.
### Switch playback to proxies
Add **Toggle Proxies** to the Program Monitor toolbar using its button editor, then enable it. Check a few clips for matching picture, duration, and audio before continuing the edit.
Keep the original media available for full-quality export. If you plan to finish while offline, pin the originals too.
## Pin the files used in your timeline
Before traveling or working without a reliable connection:
1. Identify the video, audio, graphics, and proxy files used by the sequence.
2. Select those files or their containing folders in Aspect and choose **Pin**. Include the `.prproj` file or the Production projects you need.
3. Wait for pinning to complete, then open the sequence and check playback in the mode you intend to use.
Pinning a project file does not download the media it references. If proxy playback is enabled, pin the attached proxies as well as any originals still used by the sequence. Continue opening files through the mounted Aspect drive.
For a Team Project, prepare and open the project on the workstation before going offline, and follow Adobe's offline workflow for project changes. Pinning makes the media local; it does not replace Adobe's project collaboration service.
Agree on project ownership before an offline edit. On reconnecting, let Aspect finish synchronizing before handing a shared project file to someone else, and share Team Project changes through Adobe.
Keep the media for your current sequence available locally.
Choose the local drive and capacity for Aspect's cache.
# Simple review workflow
Source: https://aspect.inc/docs/workflows/simple-review-workflow
Review media, collect feedback, compare revisions, and confirm the final version.
Use this workflow to keep feedback and revisions connected from the first review through final approval.
Open the asset in the viewer and confirm that you are reviewing the intended version.
Play the asset, inspect individual frames, or use the transcript to find important moments.
Add comments to the exact moments, locations, pages, or passages that require attention.
Use replies, mentions, reactions, and attachments to keep each conversation together.
[Upload the revised cut](/docs/getting-started/uploading-and-organizing), then add it to the existing version stack.
Compare the new version with the previous review round and confirm that the requested changes were completed.
Resolve comments after checking that each request has been addressed.
Confirm that the correct version opens by default before approving, sharing, or delivering it.
## See the review workflow
Watch the full review flow from feedback through final-version confirmation.
## Before sharing the result
* Check that unresolved comments still require action.
* Confirm whether external reviewers can access earlier versions.
* Test the share link and its permissions, including [password, expiration, and watermark settings](/docs/review-and-approve/sharing-security) when applicable.
* Make sure the intended final version opens first.
## Related guides
Preview media, navigate transcripts, and review creative work in the browser.
Add precise feedback, drawings, attachments, and replies.
Organize revisions and compare two cuts side by side.
Control what teammates and external reviewers can access.
# Display Customization
Source: https://aspect.inc/docs/workspace-management/display-customization
Adjust layout, thumbnails, metadata, filters, and sorting in your Aspect library.
Display controls change how files and folders are shown in your Aspect library. They do not resize, crop, move, or modify the original files.
## Open the display controls
1. Open the project or folder you want to browse.
2. Select **Display** above the library.
3. Choose a layout and adjust the options you need.
4. Review the library to confirm that the view works for your task.
## Choose a layout
Aspect provides two library layouts:
* **Grid** emphasizes thumbnails and is useful for visual browsing.
* **List** creates a denser view that is useful when filenames and metadata matter more than large previews.
Switching layouts changes only the library view. It does not change the files or their folder locations.
## Adjust row size
Use **Row size** to make items more compact or give previews more room.
A smaller size helps you scan more items at once. A larger size makes thumbnails easier to inspect.
## Set the thumbnail aspect ratio
Choose the shape used for thumbnails:
* **16:9**
* **4:3**
* **1:1**
* **9:16**
Choose a ratio that matches the material you review most often. For example, 9:16 works well for vertical media, while 16:9 works well for widescreen footage.
The selected ratio changes the thumbnail frame only. It does not crop or reformat the original asset.
## Choose Fit or Fill
Use **Thumbnail fit** to control how a preview sits inside its thumbnail frame.
* **Fit** shows the complete preview. Empty space may appear around media whose shape does not match the selected ratio.
* **Fill** covers the entire thumbnail frame. Parts of the preview may be cropped at the edges.
Fit and Fill affect thumbnails only. The complete asset remains available when you open it.
## Show metadata
Use [Metadata](/docs/workflows/metadata) to choose which fields appear with items in the library.
Showing only the fields you need can make a list easier to scan. Useful fields depend on your workflow and may include status, owner, dates, production details, or technical metadata.
Display settings control where metadata appears. Edit a field through the asset's metadata controls when its value needs to change.
## Flatten folders
Turn on **Flatten folders** to view items from nested folders together in one combined library view.
Turn it off when you want to browse the existing folder hierarchy.
Flattening changes the view only. It does not move files, remove folders, or change the source organization.
## Filter the library
Filters help narrow the current library to items that match selected metadata.
1. Select **Add filter**.
2. Choose a metadata field.
3. Choose an available condition, such as **is**, **is not**, **is empty**, or **is not empty**.
4. Select a value when the condition requires one.
5. Add another filter if needed, or remove a filter to broaden the results.
Clear filters when you want to return to the complete library.
## Sort the library
Use sorting to control the order of visible items.
1. Open the sort control.
2. Choose the field to sort by.
3. Choose **Ascending** or **Descending**.
4. Select **Clear sorting** to return to the default order.
Sorting changes order only. It does not move assets between folders.
## Display settings and sharing
Display controls organize your internal library view. They do not determine what a guest can access through a share link.
Use a [collection](/docs/share-and-present/collections) when you need to curate a specific group of assets for a client, reviewer, or presentation. Review [sharing and permissions](/docs/share-and-present/sharing-and-permissions) before sending the link.
## Recommended setups
### Browse visual selects
* Use **Grid**.
* Choose a thumbnail ratio that matches the media.
* Use **Fit** when seeing the full frame matters.
* Increase the size when comparing visual details.
### Recommended: review video files
* Use **List** for a compact, scannable view.
* Add a filter where **Filetype** is **Video**.
* Show the metadata fields needed for review.
* Sort the results into the order you need.
### Find items across nested folders
* Turn on **Flatten folders**.
* Add a filter to narrow the combined results.
* Clear the filter and turn off Flatten folders when you want to return to the folder hierarchy.
## Use Aspect Agent to change the view
You can ask [Aspect Agent](/docs/asset-intelligence/ask-aspect) to configure the current library view for you. Describe the result you want instead of changing each display control manually.
For example:
* "Switch to List view and show only videos."
* "Use Grid view with 9:16 thumbnails and Fill."
Review the updated library and ask Aspect Agent to refine it if you want a different layout, filter, or sort order.
## Related guides
* [Collections](/docs/share-and-present/collections)
* [Sharing and permissions](/docs/share-and-present/sharing-and-permissions)
# Notifications
Source: https://aspect.inc/docs/workspace-management/notifications
## How notifications work
Aspect sends notifications when relevant activity happens in your workspace.
You can receive notifications when someone:
* Comments on an asset you uploaded
* [Mentions you in a comment](/docs/review-and-approve/commenting)
Each notification type has its own settings.
## Choose where notifications appear
You can choose one or more delivery methods for each notification type.
### In-App
See the notification while using Aspect.
### Email
Receive the notification at the email address connected to your Aspect account.
### Mobile Push
Receive the notification on a supported mobile device. For iPhone setup and troubleshooting, see [iOS mobile app](/docs/guides/ios-mobile-app).
You can enable more than one delivery method for the same activity.
For example, you can receive mentions through In-App, Email, and Mobile Push at the same time.
## Who receives notifications
New comment notifications are sent to the person who uploaded the asset.
Mention notifications are sent to the person mentioned in the comment.
Reply notifications are sent to the person whose comment received the reply.
Thread activity notifications are sent to people participating in the conversation.
Collection notifications are sent to the person who created the collection when someone adds an item.
Workspace invitation notifications are sent to the person being invited.
## Change your notification settings
1. Open your Aspect settings.
2. Select Notifications.
3. Find the activity you want to configure.
4. Open its notification menu.
5. Select In-App, Email, Mobile Push, or a combination of these methods.
6. Close the menu when you are finished.
A checkmark means that the delivery method is enabled.
Changing your settings only affects the notifications you receive. It does not change another person's notification settings.
# How to Share With Guests
Source: https://aspect.inc/docs/workspace-management/sharing-with-guests
## Share with guests
In Aspect, a **guest** is anyone who opens a share link. Guests do not need an Aspect account, do not consume a paid workspace seat, and have nothing to install to view shared content in a browser.
Guest access works well for clients, reviewers, freelancers, and anyone else who only needs access to specific content. To give someone ongoing access to projects or the wider workspace, invite them as a member instead.
## Create a guest link
Create a share link for the specific file, folder, or collection you want guests to access.
Select the asset, folder, collection, or project you want to share, then click **Share**.
Sharing a folder or collection gives guests access to everything inside it.
Create a new link and give it a name. The name is visible to your team and helps you remember who the link is for.
Every share link allows viewing. You can also choose additional permissions such as commenting and downloading; see [Sharing and permissions](/docs/share-and-present/sharing-and-permissions) for the full permission model and recommended settings.
Choose what people using the link can do.
Depending on the content and available settings, guests may be allowed to:
* Leave comments.
* Download files.
* Upload or organize content.
* View or edit selected metadata.
* Mount a shared folder.
If needed, [add a password or expiration date](/docs/review-and-approve/sharing-security).
Choose an expiration preset such as 7, 30, or 90 days, or set a custom date and time.
Copy the link and send it to the recipient. When they open it, they are treated as a guest automatically.
## Embed shared videos
### Embed with code
[Here’s how to embed if you want to use code.](/docs/share-and-present/embed-videos#embed-with-code)
### Embed with a link
[Here’s how to embed if you want to use a link.](/docs/share-and-present/embed-videos#embed-with-a-link)
## What guests can access
Guests can only access the content included in the share link. Sharing a folder or collection includes the items inside it, but does not expose the rest of your workspace.
Every share link allows guests to view the shared content. Depending on the resource and the permissions you enable, guests may also be able to:
* Play shared video and audio.
* Leave comments and replies.
* Download files.
* View earlier versions.
* View or edit selected metadata.
* Upload or organize content in a shared folder.
* Mount an eligible shared folder through Instant Access.
Guests cannot use the link to browse other projects, open content outside the shared location, access workspace settings, perform actions that are disabled for the link, or see internal comments.
Access ends when the link is disabled, deleted, or reaches its expiration date. Changes to a link's permissions affect everyone using that link.
Open the link in a private browser window before sending it. This shows you the guest experience without your workspace access.
Review the complete permission model and choose the right access for each audience.