# Replace the background in iOS

> Replace the live iOS camera background with a color, image, or looping video using Nosmai segmentation.

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

Product: Nosmai Effects
Group: guide
Source: https://nosmai.com/docs/effects/guides/background/replace-the-background/ios/

## Prerequisites

- A working [iOS quickstart](/docs/effects/quickstart/ios/)
- Advanced filters enabled for the project
- A bundled image or local video URL

## Replace with an image

```objc
NosmaiBackgroundSegmentationConfig *config =
    [[NosmaiBackgroundSegmentationConfig alloc] init];
config.mode = NosmaiBackgroundSegmentationModeImage;
config.replacementImage = [UIImage imageNamed:@"studio_background"];

[[NosmaiCore shared].effects setBackgroundSegmentation:config];
```

For a color, use `NosmaiBackgroundSegmentationModeColor` and set
`replacementColor`. For a looping video, use
`NosmaiBackgroundSegmentationModeVideo` and a readable local
`replacementVideoURL`.

## Change or clear it

Apply another configuration to switch the background. Clear manual
segmentation when leaving the feature:

```objc
[[NosmaiCore shared].effects clearBackgroundSegmentation];
```

## Quality guidance

Use a well-lit subject, a background that contrasts with hair and clothing,
and an asset near the preview aspect ratio. Low light, motion blur, transparent
objects, and heavy occlusion can soften the segmentation edge.

## Verify it worked

The subject should remain visible while the source background is replaced.
Rotate the device and test both cameras before release.

## Common errors

| Symptom | Cause | Fix |
| --- | --- | --- |
| Image does not appear | Asset was not added to the application bundle | Check target membership and `imageNamed:` result |
| Video does not start | URL is remote or unreadable | Copy the supported video into a readable local URL |
| Edge quality is unstable | Lighting or motion is unsuitable | Improve lighting, reduce motion blur, and test at 720p |

## Next steps

- [Blur the background in iOS](/docs/effects/guides/background/blur-the-background/ios/)
- [Record video in iOS](/docs/effects/guides/output/record-video/ios/)
- [Review performance limits](/docs/effects/limits-and-performance/)

## References

- [iOS platform guide](/docs/effects/platforms/ios/)
- [Rendering pipeline](/docs/effects/concepts/how-the-pipeline-works/)