---
name: "chooseMedia"
mode: "kit"
versionRequirements:
  - { name: "BaseKit", version: "2.5.0" }
platform:
  - "iOS"
  - "Android"
async: true
---

## chooseMedia

> [VERSION] BaseKit >= 2.5.0

> [PLATFORM] iOS, Android

> ⚡ **Supports Promise** — Returns a Promise when success / fail / complete callbacks are omitted.

### Description

Capture or select images/videos from the device album. Permissions: [scope.camera, scope.writePhotosAlbum]

### Parameters

| Property | Type | Required | Default | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `count` | `number` | No | `9` | `2.5.0` | Maximum number of files that can be selected. Note: On Android 13 and above, the system image picker is used, and this field has no effect |
| `mediaType` | `string` | No | `"image"` | `2.5.0` | Selection type, default is 'image' 'image' can only capture or select images from the album 'video' can only capture or select videos from the album |
| `sourceType` | `string[]` | No | `["album", "camera"]` | `2.5.0` | Sources for selecting images/videos, default ['album', 'camera'] 'album' select from album 'camera' capture with camera |
| `maxDuration` | `number` | No | `10` | `2.5.0` | Maximum recording duration for captured videos, in seconds. Default 10s Range: 3s to 60s. Not limited for album selections |
| `isFetchVideoFile` | `boolean` | No | `true` | `3.14.2` | iOS only Whether to copy the video: Default true: copy the video; returns the copied video path and the cover image path false: do not copy; returns the album video path and the cover image path |
| `isClipVideo` | `boolean` | No | `false` | `3.14.2` | iOS only Whether to crop videos selected from the album Default false: do not crop |
| `maxClipDuration` | `number` | No | `60` | `3.14.2` | Maximum clip duration, in seconds. Default 60s Takes effect only when isClipVideo is true Range: 60s to 600s. Videos shorter than 15s are not clipped |
| `isGetAlbumFileName` | `boolean` | No | `false` | `3.14.2` | iOS only Whether to use the same exported file name as in the album Default false: use a unique file name each time |
| `isClipVideoAndroid` | `boolean` | No | `true` | `3.35.1` | Android-only; OEM customization; will be merged into isClipVideo later. Whether videos selected from the album need cropping. Default: true. Crops the video, consistent with existing behavior. |
| `complete` | `() => void` | No | - | - | Callback invoked when the API call completes (runs on both success and failure) |
| `success` | `(params: Object) => void` ↓see below | No | - | - | Callback invoked on successful API call |
| `fail` | `(params: Object) => void` ↓see below | No | - | - | Callback invoked on failed API call |

#### success callback parameters

| Property | Type | Since | Description |
| --- | --- | --- | --- |
| `type` | `string` | `3.2.6` | File type 'image' Image 'video' Video |
| `tempFiles` | `TempMediaFileCB[]` | `3.2.6` | List of local temporary files |

#### fail callback parameters

| Property | Type | Description |
| --- | --- | --- |
| `errorMsg` | `string` | Error message |
| `errorCode` | `string \| number` | Error code |
| `innerError` | `Object` | Error extensions |

##### fail(params).innerError properties

| Property | Type | Description |
| --- | --- | --- |
| `errorCode` | `string \| number` | Extended error code |
| `errorMsg` | `string` | Extended error information |


### Referenced Types

##### `interface` TempMediaFileCB

| Property | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `tempFilePath` | `string` | Yes | `3.2.6` | Local temporary file path (local path) |
| `size` | `number` | Yes | `3.2.6` | Local temporary file size, in bytes (B) |
| `duration` | `number` | Yes | `3.2.6` | Video duration |
| `height` | `number` | Yes | `3.2.6` | Video height |
| `width` | `number` | Yes | `3.2.6` | Video width |
| `thumbTempFilePath` | `string` | Yes | `3.2.6` | Temporary file path of the video thumbnail |
| `fileType` | `string` | Yes | `3.2.6` | File type 'image'  Image 'video'  Video |
| `originalVideoPath` | `string` | Yes | `3.14.2` | Original video URL from the gallery |


### Examples

```tsx
// Capture or select image/video (invokes the system picker; manual selection required)
ty.chooseMedia({
  count: 1,
  mediaType: "image",
  sourceType: ["album", "camera"],
  maxDuration: 10,
  success: data => console.log("Selected:", data.type, data.tempFiles),
  fail: error => console.error(error),
});
```