# Migrate from bitHumanKit

URL: https://docs.bithuman.ai/platforms/swift/migrate-from-bithumankit

> Move an iPhone, iPad or Mac app from the retired bitHumanKit product to Expression2 or Essence2Kit.

`bitHumanKit` is retired and is no longer a product of the Swift package. Move your app to `Expression2` or `Essence2Kit`, the two products that render the avatar on the device.

## What replaces it

| With bitHumanKit | Now |
|---|---|
| Package URL `https://github.com/bithuman-product/homebrew-bithuman.git` | `https://gitlab.com/bithuman/sdk/homebrew-bithuman` (package identity `homebrew-bithuman`) |
| the `bitHumanKit` product | the `Expression2` or `Essence2Kit` product |
| `import bitHumanKit` | `import Expression2` or `import Essence2Kit` |
| `config.apiKey` on `VoiceChatConfig` | `Expression2Credential.set(secret)` or `Essence2Credential.set(secret)`, before you create an engine |
| iPhone 16 Pro or iPad Pro M4 or newer, plus two Apple memory entitlements | Expression 2: iOS 16 or macOS 13 or newer. Essence 2: iOS 26 or macOS 26 or newer. The engines need no entitlement |

Pick `Expression2` to animate any character from one portrait, or `Essence2Kit` for a photoreal person. The [iOS & iPadOS](https://docs.bithuman.ai/platforms/ios) page compares the two.

## What the products do not include

`bitHumanKit` was a voice agent: `VoiceChat` listened, answered with a language model and spoke. `Expression2` and `Essence2Kit` render the avatar only. You feed 16 kHz mono speech in and take lip-synced frames out.

Keep your own speech recognition, language model and speech synthesis, and pass each reply's audio to the engine. `VoiceChat`, `AvatarRendererView`, `HardwareCheck`, `ExpressionWeights` and `AgentCatalog` have no counterpart. Every entry point the products do have is on the [Swift reference](https://docs.bithuman.ai/platforms/swift/reference).

## Steps

1. **Remove the old product.** In `Package.swift`, delete the `bitHumanKit` product line from your target. In Xcode, open your target's *General → Frameworks, Libraries, and Embedded Content* and remove `bitHumanKit`.
2. **Point the package at its current URL.** If your project lists the package at its old GitHub URL, remove it under *Project → Package Dependencies*, then add it again with the URL below.
3. **Add the product your app uses:**

In Xcode choose *File → Add Package Dependencies…* and paste `https://gitlab.com/bithuman/sdk/homebrew-bithuman`. In a `Package.swift`:

```swift
.package(url: "https://gitlab.com/bithuman/sdk/homebrew-bithuman", from: "2.23.1")
// then attach the product your target uses:
//   .product(name: "Expression2", package: "homebrew-bithuman")
//   .product(name: "Essence2Kit", package: "homebrew-bithuman")
//   .product(name: "Essence2", package: "homebrew-bithuman")
```

The products:

| Product | Import | What it is | Deployment target |
|---|---|---|---|
| `Expression2` | `import Expression2` | the Expression 2 engine with a Swift API | iOS 16 · macOS 13 |
| `Essence2Kit` | `import Essence2Kit` | the Essence 2 engine with a Swift API; it includes `Essence2` | iOS 26 · macOS 26 |
| `Essence2` | `import Essence2` | the Essence 2 engine as a C library, for C, C++ and plugins | iOS 26 · macOS 26 |

Every product ships `ios-arm64`, `ios-arm64-simulator` (arm64 only) and `macos-arm64`.

4. **Replace the imports.** Change `import bitHumanKit` to `import Expression2` or `import Essence2Kit`.
5. **Set the credential.** Replace `config.apiKey` with `Expression2Credential.set(secret)` or `Essence2Credential.set(secret)` ([Authenticate](https://docs.bithuman.ai/platforms/ios#authenticate)).
6. **Render.** Replace the `VoiceChat` and `AvatarRendererView` code with the engine loop in [Run your first avatar](https://docs.bithuman.ai/platforms/ios#run-your-first-avatar).
7. **Remove what only `bitHumanKit` needed.** Delete the `com.apple.developer.kernel.increased-memory-limit` and `com.apple.developer.kernel.extended-virtual-addressing` entitlements, unless other code in your app needs them. Delete `NSSpeechRecognitionUsageDescription` unless your own code uses speech recognition. Keep `NSMicrophoneUsageDescription` if your app records the user.
8. **Update and build.** Choose *File → Packages → Update to Latest Package Versions* in Xcode, or run `swift package update`, then build for a physical device.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| The build fails with `product 'bitHumanKit' not found in package 'homebrew-bithuman'` | a target still lists the retired product | remove the product line (step 1) |
| `No such module 'bitHumanKit'` | a source file still imports it | change the import (step 4) |
| Essence 2 does not start on an older iPhone | Essence 2 needs iOS 26 or newer | use `Expression2` on that device |

More fixes, by symptom, are on [Swift troubleshooting](https://docs.bithuman.ai/platforms/swift/troubleshooting).