# iOS quickstart

> Initialize Nosmai Effects, attach its processed camera preview, start capture, and apply a beauty effect on iOS.

> For AI agents: the complete documentation index is at https://nosmai.com/llms/effects.txt

Product: Nosmai Effects
Group: get-started
Source: https://nosmai.com/docs/effects/quickstart/ios/

## Prerequisites

- [Nosmai Effects installed for iOS](/docs/effects/installation/ios/)
- iOS deployment target 15 or later
- A physical arm64 iPhone or iPad
- A [Nosmai licence key](/docs/effects/license-key/) bound to the signed bundle ID
- `NSCameraUsageDescription` in the application `Info.plist`

## 1. Confirm camera permission text

```xml
<key>NSCameraUsageDescription</key>
<string>This app uses the camera for real-time filters and effects.</string>
```

The system terminates an app that requests camera access without this key.

## 2. Request camera access

Request permission before presenting the processed preview:

```objc
[AVCaptureDevice requestAccessForMediaType:AVMediaTypeVideo
                         completionHandler:^(BOOL granted) {
    dispatch_async(dispatch_get_main_queue(), ^{
        if (granted) {
            [self initializeNosmai];
        }
    });
}];
```

Skip the prompt when authorization is already granted, and show an app-owned
settings message when access was denied.

## 3. Initialize Nosmai once

Initialize from the application owner and continue from the successful
completion:

```objc
[[NosmaiCore shared]
    initializeWithAPIKey:@"NOSMAI-YOUR-IOS-LICENSE-KEY"
              completion:^(BOOL success, NSError *error) {
    if (!success) {
        NSLog(@"Nosmai initialization failed: %@", error.localizedDescription);
        return;
    }

    [self startNosmaiCamera];
}];
```

Replace the documentation key with application-owned configuration.

## 4. Attach and start the preview

Attach the SDK camera to an existing `UIView` owned by the camera controller:

```objc
NosmaiCore *core = [NosmaiCore shared];
NosmaiCameraConfig *config = [[NosmaiCameraConfig alloc] init];
config.position = NosmaiCameraPositionFront;
config.sessionPreset = AVCaptureSessionPresetHigh;
config.frameRate = 30;

[core.camera updateConfiguration:config];
[core.camera attachToView:self.previewView];
[core.camera startCapture];
[core.effects applySkinSmoothing:0.4f];
```

Keep camera attachment and preview updates on the main thread.

## 5. Stop capture when leaving

Release the preview when its screen is no longer visible:

```objc
[[NosmaiCore shared].camera stopCapture];
[[NosmaiCore shared].camera detachFromView];
```

Call `cleanup` only when the application no longer needs the shared SDK state.
Build and run on a physical device, not iOS Simulator.

## Verify it worked

You should see the front-camera preview, the status `Camera ready with skin
smoothing`, and a visible smoothing change at level `0.4`. Leave the screen and
confirm the iOS camera indicator turns off. Return and confirm capture restarts
without a second initialization.

## Common errors

| Error | Cause | Fix |
| --- | --- | --- |
| `SDK initialization failed` | Native initialization or licence setup did not complete | Inspect the accompanying `NSError`, key, bundle ID, and network access |
| `SDK not initialized` | Camera or effects API was accessed before completion | Move camera setup inside the successful initialization completion |
| `Camera preview not available` | No preview view is attached | Call `attachToView:` before `startCapture` |
| `Camera not active` | Capture-dependent operation ran before the camera started | Confirm permission and check the Boolean result from `startCapture` |
| `building for iOS Simulator, but linking in object file built for iOS` | The framework has no simulator slice | Select a physical arm64 iOS device |

## Next steps

- [Apply a beauty filter on iOS](/docs/effects/guides/effects/apply-a-beauty-filter/ios/)
- [Replace the background in iOS](/docs/effects/guides/background/replace-the-background/ios/)
- [Download a Cloud Filter in iOS](/docs/effects/guides/filters/download-a-cloud-filter/ios/)
- [Render processed frames for streaming in iOS](/docs/effects/guides/streaming/render-frames-off-screen/ios/)

## References

- [iOS installation](/docs/effects/installation/ios/)
- [How the pipeline works](/docs/effects/concepts/how-the-pipeline-works/)
- [Nosmai Effects](https://nosmai.com/effects/)
- [Nosmai Effects pricing](https://nosmai.com/effects/#pricing)