feat: Add deeplinks for recording controls + Raycast extension

apps/desktop/src-tauri/src/deeplink_actions.rs

@@ -26,6 +26,16 @@ pub enum DeepLinkAction {
         mode: RecordingMode,
     },
     StopRecording,
+    PauseRecording,
+    ResumeRecording,
+    TogglePauseRecording,
+    RestartRecording,
+    SetMicrophone {
+        label: Option<String>,
+    },
+    SetCamera {
+        id: Option<DeviceOrModelID>,
+    },
     OpenEditor {
         project_path: PathBuf,
     },
@@ -146,6 +156,28 @@ impl DeepLinkAction {
             DeepLinkAction::StopRecording => {
                 crate::recording::stop_recording(app.clone(), app.state()).await
             }
+            DeepLinkAction::PauseRecording => {
+                crate::recording::pause_recording(app.clone(), app.state()).await
+            }
+            DeepLinkAction::ResumeRecording => {
+                crate::recording::resume_recording(app.clone(), app.state()).await
+            }
+            DeepLinkAction::TogglePauseRecording => {
+                crate::recording::toggle_pause_recording(app.clone(), app.state()).await
+            }
+            DeepLinkAction::RestartRecording => {
+                crate::recording::restart_recording(app.clone(), app.state())
+                    .await
+                    .map(|_| ())
+            }
+            DeepLinkAction::SetMicrophone { label } => {
+                let state = app.state::<ArcLock<App>>();
+                crate::set_mic_input(state, label).await
+            }
+            DeepLinkAction::SetCamera { id } => {
+                let state = app.state::<ArcLock<App>>();
+                crate::set_camera_input(app.clone(), state, id, None).await
+            }
             DeepLinkAction::OpenEditor { project_path } => {
                 crate::open_project_from_path(Path::new(&project_path), app.clone())
             }

apps/desktop/src-tauri/src/lib.rs

@@ -470,7 +470,7 @@ impl App {
 #[tauri::command]
 #[specta::specta]
 #[instrument(skip(state))]
-async fn set_mic_input(state: MutableState<'_, App>, label: Option<String>) -> Result<(), String> {
+pub(crate) async fn set_mic_input(state: MutableState<'_, App>, label: Option<String>) -> Result<(), String> {
     let desired_label = label;
 
     let (mic_feed, studio_handle, previous_label) = {
@@ -573,7 +573,7 @@ fn get_system_diagnostics() -> cap_recording::diagnostics::SystemDiagnostics {
 #[specta::specta]
 #[instrument(skip(app_handle, state))]
 #[allow(unused_mut)]
-async fn set_camera_input(
+pub(crate) async fn set_camera_input(
     app_handle: AppHandle,
     state: MutableState<'_, App>,
     id: Option<DeviceOrModelID>,

extensions/raycast/DEEPLINKS.md

@@ -0,0 +1,191 @@
+# Cap Deeplinks
+
+Cap supports deeplinks for controlling recordings and other app functionality. This enables integration with tools like Raycast, Alfred, Shortcuts, and custom scripts.
+
+## URL Scheme
+
+Cap uses the `cap-desktop://` URL scheme on macOS and Windows.
+
+## Action Format
+
+Actions are sent as JSON in the `value` query parameter:
+
+```
+cap-desktop://action?value=<URL-encoded JSON>
+```
+
+**Important:** The JSON value MUST be URL-encoded!
+
+## Available Actions
+
+### Recording Controls
+
+Unit variants are serialized as JSON strings (not objects):
+
+#### Stop Recording
+```json
+"stop_recording"
+```
+
+#### Pause Recording
+```json
+"pause_recording"
+```
+
+#### Resume Recording
+```json
+"resume_recording"
+```
+
+#### Toggle Pause/Resume
+```json
+"toggle_pause_recording"
+```
+
+#### Restart Recording
+Stops and immediately restarts with the same settings:
+```json
+"restart_recording"
+```
+
+#### Start Recording
+Struct variant (serialized as object):
+```json
+{
+  "start_recording": {
+    "capture_mode": {"screen": "Main Display"},
+    "camera": null,
+    "mic_label": null,
+    "capture_system_audio": false,
+    "mode": "instant"
+  }
+}
+```
+
+**capture_mode options:**
+- `{"screen": "Display Name"}` - Record a specific display
+- `{"window": "Window Name"}` - Record a specific window
+
+**mode options:**
+- `"instant"` - Quick recording with immediate upload
+- `"studio"` - Full editing capabilities
+
+### Input Controls
+
+#### Set Microphone
+```json
+{"set_microphone": {"label": "MacBook Pro Microphone"}}
+```
+
+Set to `null` to disable:
+```json
+{"set_microphone": {"label": null}}
+```
+
+#### Set Camera
+```json
+{"set_camera": {"id": "camera-device-id"}}
+```
+
+Set to `null` to disable:
+```json
+{"set_camera": {"id": null}}
+```
+
+### App Controls
+
+#### Open Settings
+```json
+{"open_settings": {"page": null}}
+```
+
+Open a specific settings page:
+```json
+{"open_settings": {"page": "recordings"}}
+```
+
+#### Open Editor
+```json
+{"open_editor": {"project_path": "/path/to/project.cap"}}
+```
+
+## Examples
+
+### Shell Script (macOS)
+
+```bash
+#!/bin/bash
+
+# Stop recording (note: unit variant is a string, not object)
+open "cap-desktop://action?value=%22stop_recording%22"
+
+# Toggle pause
+open "cap-desktop://action?value=%22toggle_pause_recording%22"
+
+# Set microphone (struct variant)
+open "cap-desktop://action?value=%7B%22set_microphone%22%3A%7B%22label%22%3A%22MacBook%20Pro%20Microphone%22%7D%7D"
+```
+
+### AppleScript
+
+```applescript
+tell application "System Events"
+    open location "cap-desktop://action?value=%22stop_recording%22"
+end tell
+```
+
+### JavaScript/Node.js
+
+```javascript
+const { exec } = require('child_process');
+
+function capAction(action) {
+  const json = JSON.stringify(action);
+  const encoded = encodeURIComponent(json);
+  const url = `cap-desktop://action?value=${encoded}`;
+  exec(`open "${url}"`);
+}
+
+// Stop recording (unit variant = string)
+capAction("stop_recording");
+
+// Toggle pause (unit variant = string)
+capAction("toggle_pause_recording");
+
+// Set microphone (struct variant = object)
+capAction({ set_microphone: { label: "MacBook Pro Microphone" } });
+```
+
+### Python
+
+```python
+import subprocess
+import json
+import urllib.parse
+
+def cap_action(action):
+    json_str = json.dumps(action)
+    encoded = urllib.parse.quote(json_str)
+    url = f"cap-desktop://action?value={encoded}"
+    subprocess.run(["open", url])
+
+# Stop recording (unit variant = string)
+cap_action("stop_recording")
+
+# Toggle pause (unit variant = string)
+cap_action("toggle_pause_recording")
+
+# Set microphone (struct variant = dict)
+cap_action({"set_microphone": {"label": "MacBook Pro Microphone"}})
+```
+
+## Raycast Extension
+
+A full Raycast extension is included in `extensions/raycast/`. See its README for installation instructions.
+
+## Troubleshooting
+
+1. **Cap must be running** - Deeplinks only work when Cap is open
+2. **URL encoding** - Make sure the JSON is properly URL-encoded
+3. **Unit vs Struct variants** - Unit actions (stop, pause, etc.) are JSON strings like `"stop_recording"`, not objects like `{"stop_recording": {}}`
+4. **Permissions** - Some actions require an active recording session

extensions/raycast/README.md

@@ -0,0 +1,74 @@
+# Cap Raycast Extension
+
+Control [Cap](https://cap.so) screen recording from Raycast.
+
+## Features
+
+- **Start Recording** - Start a new screen recording
+- **Stop Recording** - Stop the current recording
+- **Pause Recording** - Pause the current recording  
+- **Resume Recording** - Resume a paused recording
+- **Toggle Pause** - Toggle pause/resume on current recording
+- **Restart Recording** - Restart the current recording
+- **Open Settings** - Open Cap settings
+
+## Requirements
+
+- [Cap](https://cap.so) must be installed and running
+- macOS and Windows supported (Cap deeplinks use the `cap-desktop://` scheme)
+
+## How It Works
+
+This extension uses Cap's deeplink API to control recordings. Each command sends a URL like:
+
+```
+cap-desktop://action?value=%22stop_recording%22
+```
+
+Note: Unit actions (stop, pause, resume, etc.) are sent as JSON strings, while actions with parameters are sent as JSON objects.
+
+## Installation
+
+1. Clone this repository
+2. Run `npm install` in the `extensions/raycast` directory
+3. Run `npm run dev` to start development
+4. Or `npm run build` to build for production
+
+## Configuration
+
+The extension supports the following preferences (configurable in Raycast):
+
+- **Display Name** - Name of the display to record (leave empty for primary display)
+- **Recording Mode** - Choose between "instant" or "studio" mode
+- **Capture System Audio** - Whether to capture system audio by default
+
+## Available Deeplinks
+
+| Action | Deeplink Value (URL-encoded) |
+|--------|------------------------------|
+| Stop Recording | `%22stop_recording%22` |
+| Pause Recording | `%22pause_recording%22` |
+| Resume Recording | `%22resume_recording%22` |
+| Toggle Pause | `%22toggle_pause_recording%22` |
+| Restart Recording | `%22restart_recording%22` |
+| Set Microphone | `%7B%22set_microphone%22%3A%7B%22label%22%3A%22Microphone%20Name%22%7D%7D` |
+| Set Camera | `%7B%22set_camera%22%3A%7B%22id%22%3A%22camera-id%22%7D%7D` |
+| Open Settings | `%7B%22open_settings%22%3A%7B%22page%22%3Anull%7D%7D` |
+
+### Raw JSON Values (before URL encoding)
+
+Unit actions (no parameters):
+- `"stop_recording"`
+- `"pause_recording"`
+- `"resume_recording"`
+- `"toggle_pause_recording"`
+- `"restart_recording"`
+
+Struct actions (with parameters):
+- `{"set_microphone":{"label":"Microphone Name"}}`
+- `{"set_camera":{"id":"camera-id"}}`
+- `{"open_settings":{"page":null}}`
+
+## License
+
+MIT