---
name: "chooseMedia"
mode: "kit"
versionRequirements:
  - { name: "BaseKit", version: "2.5.0" }
  - { name: "@ray-js/ray", version: "0.5.9" }
platform:
  - "iOS"
  - "Android"
async: true
---

## chooseMedia

> [VERSION] BaseKit >= 2.5.0 | @ray-js/ray >= 0.5.9

> [PLATFORM] iOS, Android

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

### Description

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

### Parameters

| Property | Type | Required | Default | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `count` | `number` | No | `9` | `2.5.0` | Maximum number of files to select. 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 'video' can only capture or select videos |
| `sourceType` | `string[]` | No | `["album", "camera"]` | `2.5.0` | Sources for selecting images/videos, default ['album', 'camera'] 'album' select from album 'camera' capture using the camera |
| `maxDuration` | `number` | No | `10` | `2.5.0` | Maximum recording duration for captured video in seconds, default 10s Range: 3s to 60s. No limit for videos from the album |
| `isFetchVideoFile` | `boolean` | No | `true` | `3.14.2` | iOS only Whether to copy the video: Default true: copy the video and return the copied video path and cover path false: do not copy; return the album video path and cover image path |
| `isClipVideo` | `boolean` | No | `false` | `3.14.2` | iOS only Whether to trim videos selected from the album Default false: do not trim |
| `maxClipDuration` | `number` | No | `60` | `3.14.2` | Maximum trim length in seconds, default 60s Takes effect only when isClipVideo is true Range: 60s to 600s. Videos shorter than 15s are not trimmed |
| `isGetAlbumFileName` | `boolean` | No | `false` | `3.14.2` | iOS only Whether to use the exported filename identical to the album filename Default false: use a unique filename each time |
| `isClipVideoAndroid` | `boolean` | No | `true` | `3.35.1` | This parameter is only effective on Android. 芯图定制. To be merged into isClipVideo later Whether the video selected from the album needs cropping Default is true: crop the video, consistent with the original behavior |
| `complete` | `() => void` | No | - | - | Completion callback (executed on both success and failure) |
| `success` | `(params: Object) => void` ↓see below | No | - | - | Callback on successful API call |
| `fail` | `(params: Object) => void` ↓see below | No | - | - | Failure callback |

#### 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 extension |

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

| Property | Type | Description |
| --- | --- | --- |
| `errorCode` | `string \| number` | Error extension code |
| `errorMsg` | `string` | Error extension message |


### Referenced Types

##### `interface` TempMediaFileCB

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


### Examples

#### Demo

```tsx
import { chooseMedia } from '@ray-js/ray'

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