> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phones.farm/llms.txt
> Use this file to discover all available pages before exploring further.

# Screen & Casting

> Low-latency H.264 / MJPEG screen streaming endpoints, screenshot capture, and frame buffer access APIs.

## 1.Get Screenshot

Get real-time screenshot of specified device, supports various image formats and quality settings.

### Endpoint Description

#### Endpoint Type

```
getScreenShot
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| deviceId | string | Yes | Device ID |
| quality | number | No | Image quality (0-1), default 0.8 |
| format | string | No | Return format: `'bmp'` or default format |

#### Response Payload

Returns binary image data:

### Basic Usage

```
// Get screenshot (default settings)
const screenshot = await apiInvoke('getScreenShot', {
    deviceId: 'P72578581E07'
});

// Save as file
const fs = require('fs');
fs.writeFileSync('screenshot.png', screenshot);
```

## 2.Crop Screen Shot

Crop a specified area from the device screenshot and return the cropped image.

**Important Note**

**This method** ********only returns BMP image format******, other formats are not supported.**

### Endpoint Description

#### Endpoint Type

```
cropScreenShot
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| deviceId | string | Yes | Device ID |
| rect | number\[] | Yes | Crop area, format: `[x1, y1, x2, y2]`, unit: pixels |

#### Response Payload

Returns cropped image binary data (**BMP format**):

### Basic Usage

```
// Crop screenshot
// rect: [x1, y1, x2, y2] - top-left and bottom-right coordinates
const croppedImage = await apiInvoke('cropScreenShot', {
    deviceId: 'P72578581E07',
    rect: [100, 100, 300, 400]  // Area from (100, 100) to (300, 400)
});

// Save as file (Note: returns BMP format)
const fs = require('fs');
fs.writeFileSync('cropped.bmp', croppedImage);
```

### Notes

1. **Format Limitation**: This method always returns BMP format, other formats cannot be specified
2. **Coordinate Range**: Coordinates and dimensions in `rect` parameter must not exceed screen bounds
3. **Parameter Format**: `rect` must be an array of 4 numbers: `[x1, y1, x2, y2]`, where (x1, y1) is the top-left coordinate and (x2, y2) is the bottom-right coordinate

## 3.Screen Image Push

Push specified screen area image directly to custom API service for processing, suitable for various image recognition scenarios.

### Application Scenarios

This interface is particularly suitable for the following scenarios:

* 🔤 **OCR Text Recognition** - Integrate third-party OCR services (such as PaddleOCR, Tesseract, etc.)
* 🎯 **Captcha Recognition** - Use specialized captcha recognition services
* 🖼️ **Image Classification** - Identify image content, object detection
* 🤖 **AI Recognition** - Integrate any custom image AI model

💡 How It Works

**Streaming End → Capture Image → Direct POST → Your API → Return Result**

Images are sent directly from the streaming end to your API, saving decoding and redundant transmission steps, improving efficiency.

### Difference from getScreenShot

#### Comparison

| Feature | screenPush | getScreenShot |
| - | - | - |
| **Data Flow** | Streaming end → Your API | Streaming end → iClick main process → Caller |
| **Transmissions** | 1 (direct push) | 2 (first to main process, then to API) |
| **Resource Usage** | Low (not through main process) | High (requires decoding and passing in main process) |

### Endpoint Description

#### Endpoint Type

```
screenPush
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| api | string | Yes | Your API service address |
| args | object | No | Custom parameter object, will be passed as-is to API server |
| quality | number | No | Image quality (0-1), default 0.8 |
| scale | number | No | Scale ratio (0-1), default 1.0 |

#### Request Format

iClick will send POST request to your API. To save unnecessary resources, after the streaming end successfully pushes, it will not wait for the result and return it to the caller. screenPush will always return true, and you need to implement your own business callback logic.

**Request Headers:**

```
Content-Type: multipart/form-data
```

**Request Body:**

```
image: <Image binary data (screenshot)>
```

If `args` parameter is provided, all fields will be passed as additional form fields:

```
image: <Image binary data>
customField: "value"            // Your custom field
...
```

### Basic Usage

```
// Captcha recognition example
await apiInvoke('screenPush', {
    api: 'http://localhost:5000/resolve_captcha',
    args: {
        type: 'digits',
        ...
    }
});
```

## 4.Device Video Stream

Pull a device's real-time video stream directly via WebSocket. Suitable for custom players, recording, real-time analysis, and similar scenarios.

### Endpoint

```
ws://127.0.0.1:23158/player/DEVICE_ID
```

Connect directly to local port `23158` to pull the video stream.

| Parameter | Description |
| - | - |
| DEVICE\_ID | Target device ID, e.g. `P72578581E07` |

### Output

After a successful connection, the server continuously pushes an **H.264 baseline raw stream** to the client.

### Basic Usage (Node.js Example)

```
const deviceId = 'P72578581E07'
const ws = new WebSocket(`ws://127.0.0.1:23158/player/${deviceId}`)

ws.binaryType = 'arraybuffer'

ws.onmessage = (_event) => {
    // _event.data is H.264 baseline raw stream binary data
    // Pass it to your decoder / player
}

ws.onclose = () => {
    console.log('Video stream connection closed')
}

// Close the connection when the stream is no longer needed
// ws.close()
```

### ⚠️ **Important Behavior**

**The kernel server continuously monitors all stream-pulling connections for a device (including the iClick console):**

* **When a device has no stream-pulling clients, the kernel instructs the device to stop pushing, saving bandwidth and compute resources on both ends.**
* ****When your business no longer needs the cast screen data, actively close the WebSocket connection to free device and host-side resources.****


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.