> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Recording Controls

> Learn how to manage the full lifecycle of an ambient session using the recording controls in the mobile SDK

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    The Mobile SDK provides recording control methods to manage the full lifecycle of an ambient session. Use `start`, `pause`, `resume`, `end`, and `cancel` to control recordings with full state management.

    <br />

    <br />

    Each method handles errors and returns results asynchronously. The SDK manages session state transitions automatically, so you can update your UI based on the current state and handle errors appropriately.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">June 2026</span>
  </div>
</div>

The **Mobile SDK** provides you the capability to manage the full lifecycle of an ambient session using the following recording controls. These methods allow you to **start**, **pause**, **resume**, and **stop** a recording with full state management.

**What will you learn?**

In this guide, you will learn how to:

* Handle the recording lifecycle using the `start`, `pause`, `resume`, `end`, and `cancel` methods.
* Handle errors from the recording control methods.
* Understand the best practices for handling user interactions with the recording controls.

## Prerequisites

Before calling any of these methods, always ensure the SDK is **initialized** and a session has been **created** to prevent runtime errors.

<Warning>
  iOS does not allow an app to start a recording while it is in the background. If you attempt this, the SDK will throw an `appIsNotActive` error. You should handle this case by notifying the user.
</Warning>

## Recording controls

These are the recording controls that are available in the **Mobile SDK**:

### Start recording

Begin capturing audio by calling the `start` method. This transitions the session into the `Recording` state.

***

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#1a1a1a','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFE148','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#1a1a1a','nodeTextColor':'#1a1a1a','textColor':'#1a1a1a','labelTextColor':'#1a1a1a'}}}%%
stateDiagram-v2
    direction LR
    [*] --> NotCreated
    NotCreated --> Recording: start()
    Recording --> Paused: pause()
    Paused --> Recording: resume()
    Recording --> Ended: end()
    Paused --> Ended: end()
    Recording --> Canceled: cancel()
    Paused --> Canceled: cancel()
    Ended --> [*]
    Canceled --> [*]
```

***

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  do {
      // Begins the recording process for the active session.
      try SukiAmbientCore.shared.start()
  } catch {
      // Handle potential errors, e.g., session not initialized.
      print(error)
  }
  ```
</CodeGroup>

### Pause recording

To temporarily stop capturing audio while keeping the session active, call the `pause` method. This transitions the session into the `Paused` state.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  do {
      // Pauses the current recording. The session remains active.
      try SukiAmbientCore.shared.pause()
  } catch {
      // Handle errors, e.g., no active recording to pause.
      print(error)
  }
  ```
</CodeGroup>

### Resume recording

If a session is paused, you can call the `resume` method to continue capturing audio. This transitions the session into the `Recording` state.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  do {
      // Resumes a paused recording.
      try SukiAmbientCore.shared.resume()
  } catch {
      // Handle errors, e.g., the session was not in a paused state.
      print(error)
  }
  ```
</CodeGroup>

### End session

To stop the recording and begin the content generation process, call the `end` method. This is the standard way to complete a session successfully.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  do {
      // Ends the recording and triggers the note generation process.
      try SukiAmbientCore.shared.end()
  } catch {
      // Handle errors, e.g., the session was already ended.
      print(error)
  }
  ```
</CodeGroup>

### Cancel session

To stop the recording and discard all captured data, call the `cancel` method. This action cannot be **undone**.

<CodeGroup>
  ```swift Swift theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  do {
      // Stops the recording and aborts the session. No content will be generated.
      try SukiAmbientCore.shared.cancel()
  } catch {
      // Handle potential errors.
      print(error)
  }
  ```
</CodeGroup>

## Error handling

All recording control methods can throw a `SukiAmbientCoreError`. You must use a **do-catch** block to handle potential issues, such as calling a method from an invalid state.

## FAQs

<AccordionGroup>
  <Accordion title="Why can't I start a recording in the background?">
    iOS does not allow an app to start a recording while it is in the background. If you attempt this, the SDK will throw an `appIsNotActive` error. You should handle this case by notifying the user.
  </Accordion>

  <Accordion title="What happens if I call a method from an invalid state?">
    All recording control methods can throw a `SukiAmbientCoreError`. You must use a **do-catch** block to handle potential issues, such as calling a method from an invalid state.
  </Accordion>

  <Accordion title="How do I handle errors from the recording control methods?">
    All recording control methods can throw a `SukiAmbientCoreError`. You must use a **do-catch** block to handle potential issues, such as calling a method from an invalid state.
  </Accordion>

  <Accordion title="Do I need to call the `end` method to generate a note?">
    Yes, you must call the `end` method to generate a note. The `end` method transitions the session into the `Ended` state, which is required for note generation.
  </Accordion>

  <Accordion title="Can I cancel a session after it has been ended?">
    No, you cannot cancel a session after it has been ended. The `cancel` method transitions the session into the `Canceled` state, and a canceled session cannot generate a note.
  </Accordion>

  <Accordion title="Can I pause and resume a session?">
    Yes, you can pause and resume a session. The `pause` and `resume` methods transition the session into the `Paused` and `Recording` states, respectively.
  </Accordion>

  <Accordion title="Can I start a recording after it has been ended?">
    No, you cannot start a recording after it has been ended. The `start` method transitions the session into the `Recording` state, which is required for note generation.
  </Accordion>

  <Accordion title="As a developer, how do I know if a session has been ended?">
    Check the `sessionState` property to determine the current state of the session.
  </Accordion>

  <Accordion title="What is the best way to handle user interactions with the recording controls?">
    You should use the `sessionState` property to determine the current state of the session and only enable the recording controls when the session is in the `Recording` state.
  </Accordion>

  <Accordion title="If the user cancels a session, what happens to the audio and session data?">
    If the user cancels a session, the audio and session data will be discarded.
  </Accordion>
</AccordionGroup>

## Next steps

<Icon icon="file-lines" iconType="solid" /> After you have started a recording, you can proceed to the [Session status & retrieve content](/mobile-sdk/ambient-guides/session-status-and-content-retrieval) guide to check the status of the session and retrieve the generated content.