<!--
{
  "availability" : [
    "iOS: 27.0.0 -",
    "iPadOS: 27.0.0 -",
    "macCatalyst: 27.0.0 -",
    "macOS: 27.0.0 -",
    "tvOS: 27.0.0 -",
    "visionOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "MediaIntelligence",
  "identifier" : "/documentation/MediaIntelligence/FaceGroupAnalyzer",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Media Intelligence"
    ],
    "preciseIdentifier" : "s:17MediaIntelligence17FaceGroupAnalyzerC"
  },
  "title" : "FaceGroupAnalyzer"
}
-->

# FaceGroupAnalyzer

An object that detects faces in images and groups them by person.

```
final class FaceGroupAnalyzer
```

## Overview

[`FaceGroupAnalyzer`](/documentation/MediaIntelligence/FaceGroupAnalyzer) is the central object in the face analysis
pipeline. It detects faces in images, stores their data
persistently in a working directory you choose, and clusters the faces
into groups called *entities*, where each entity represents a
distinct person.

The analyzer stores all face data and cluster assignments in the
directory you pass to [`init(workingDirectory:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/init(workingDirectory:)).
This directory persists between app launches, so subsequent runs resume
from where the previous session ended. Call
[`purge(workingDirectory:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/purge(workingDirectory:)) to remove all data from
the directory.

Use [`identifyFaces(in:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/identifyFaces(in:)) to detect and match faces
in images without storing anything. This is useful for recognizing
people in new images against an existing gallery without modifying the
analyzer’s data.

## Topics

### Creating an analyzer

[`init(workingDirectory:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/init(workingDirectory:))

Creates a face group analyzer at the specified directory.

### Managing assets

[`workingDirectory`](/documentation/MediaIntelligence/FaceGroupAnalyzer/workingDirectory)

A directory where the analyzer stores its face data and metadata.

[`insertOrUpdateAssets(_:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/insertOrUpdateAssets(_:))

Adds or replaces image assets in the analyzer.

[`deleteAssets(_:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/deleteAssets(_:))

Removes the specified assets and their associated face data.

[`deleteAllAssets()`](/documentation/MediaIntelligence/FaceGroupAnalyzer/deleteAllAssets())

Removes all assets and their associated face data from the analyzer.

[`purge(workingDirectory:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/purge(workingDirectory:))

Removes all analyzer data from the specified directory.

### Updating the gallery

[`state`](/documentation/MediaIntelligence/FaceGroupAnalyzer/state-swift.property)

A value describing the current processing state of the analyzer.

[`State`](/documentation/MediaIntelligence/FaceGroupAnalyzer/State-swift.enum)

The current processing state of a face group analyzer.

[`update(subprogress:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/update(subprogress:))

Clusters faces into entities and updates their assignments.

### Retrieving faces and entities

[`allFaces`](/documentation/MediaIntelligence/FaceGroupAnalyzer/allFaces)

An async sequence of all faces in the analyzer.

[`allFacesByEntityID`](/documentation/MediaIntelligence/FaceGroupAnalyzer/allFacesByEntityID)

An async sequence of all faces, grouped by entity.

[`allEntities`](/documentation/MediaIntelligence/FaceGroupAnalyzer/allEntities)

An async sequence of all entities in the analyzer.

[`allAssetIDs`](/documentation/MediaIntelligence/FaceGroupAnalyzer/allAssetIDs)

An async sequence of all asset identifiers in the analyzer.

[`allAssetIDsByEntityID`](/documentation/MediaIntelligence/FaceGroupAnalyzer/allAssetIDsByEntityID)

An async sequence of all asset identifiers, grouped by entity.

[`Face`](/documentation/MediaIntelligence/FaceGroupAnalyzer/Face)

A face detected in an image asset.

[`Entity`](/documentation/MediaIntelligence/FaceGroupAnalyzer/Entity)

A cluster of faces that belong to the same person.

### Fetching and identifying faces

[`fetchFaces(_:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/fetchFaces(_:))

Returns the faces with the specified identifiers.

[`fetchFaces(for:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/fetchFaces(for:))

Returns the faces belonging to the specified entities.

[`fetchFaces(in:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/fetchFaces(in:))

Returns the faces from the specified assets.

[`fetchAssetIDs(for:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/fetchAssetIDs(for:))

Returns the asset identifiers for the specified entities.

[`identifyFaces(in:)`](/documentation/MediaIntelligence/FaceGroupAnalyzer/identifyFaces(in:))

Detects and identifies faces without modifying the analyzer’s data.

## Relationships

### Conforms To

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`Sendable`](/documentation/Swift/Sendable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)