Skip to main content

Screen Mirroring (scrcpy)

Endpoints for managing screen mirroring functionality using scrcpy.

Status and Control​

GET /api/scrcpy/status​

Gets the overall status of screen mirroring service.

Response:

{
  "service": "running",
  "version": "2.0",
  "activeSessions": 2,
  "maxConcurrentSessions": 5,
  "uptime": 3600
}

GET /api/scrcpy/status/:deviceId​

Gets screen mirroring status for a specific device.

Parameters:

  • deviceId: Device identifier

Response:

{
  "deviceId": "emulator-5554",
  "status": "active",
  "sessionId": "scrcpy-session-123",
  "startTime": "2024-01-01T00:00:00.000Z",
  "uptime": 1800,
  "resolution": "1080x2400",
  "bitrate": "8000000",
  "fps": 60,
  "connectionInfo": {
    "localPort": 27183,
    "remotePort": 27183,
    "protocol": "tcp"
  }
}

GET /api/scrcpy/health​

Checks the health of the screen mirroring service.

Response:

{
  "status": "ok",
  "scrcpy": {
    "version": "2.0",
    "available": true
  },
  "activeSessions": 2,
  "maxSessions": 5
}

Session Management​

POST /api/scrcpy/start​

Starts screen mirroring for a device.

Request Body:

{
  "deviceId": "emulator-5554",
  "options": {
    "maxSize": 1080,
    "bitRate": 8000000,
    "maxFps": 60,
    "lockVideoOrientation": -1,
    "stayAwake": true,
    "showTouches": false,
    "noControl": false
  }
}

Response:

{
  "success": true,
  "sessionId": "scrcpy-session-456",
  "deviceId": "emulator-5554",
  "streamUrl": "ws://localhost:3001/scrcpy/stream/scrcpy-session-456",
  "webSocketUrl": "ws://localhost:3001/scrcpy/ws/scrcpy-session-456",
  "httpUrl": "http://localhost:3001/scrcpy/http/scrcpy-session-456"
}

POST /api/scrcpy/stop​

Stops screen mirroring for a device.

Request Body:

{
  "deviceId": "emulator-5554"
}

Response:

{
  "success": true,
  "deviceId": "emulator-5554",
  "sessionId": "scrcpy-session-456",
  "uptime": 1800,
  "message": "Screen mirroring stopped"
}

POST /api/scrcpy/stop-all​

Stops all active screen mirroring sessions.

Response:

{
  "success": true,
  "stoppedSessions": 3,
  "sessions": [
    {
      "sessionId": "scrcpy-session-123",
      "deviceId": "device-1",
      "uptime": 1200
    }
  ]
}

POST /api/scrcpy/restart​

Restarts screen mirroring for a device.

Request Body:

{
  "deviceId": "emulator-5554",
  "options": {
    "bitRate": 12000000,
    "maxFps": 30
  }
}

Response:

{
  "success": true,
  "oldSessionId": "scrcpy-session-456",
  "newSessionId": "scrcpy-session-789",
  "message": "Screen mirroring restarted"
}

POST /api/scrcpy/cleanup/:deviceId​

Cleans up screen mirroring resources for a device.

Parameters:

  • deviceId: Device identifier

Request Body:

{
  "force": false
}

Response:

{
  "success": true,
  "deviceId": "emulator-5554",
  "cleanedUp": {
    "processes": 1,
    "ports": 2,
    "tempFiles": 3
  }
}

Configuration Options​

Video Options​

  • maxSize: Maximum video size (width or height)
  • bitRate: Video bitrate in bits per second
  • maxFps: Maximum frame rate
  • lockVideoOrientation: Lock video orientation (-1 to unlock, 0-3 for specific orientation)
  • crop: Crop video (format: "width:height:x:y")

Display Options​

  • displayId: Display ID to mirror (for multi-display devices)
  • renderDriver: Render driver (android, sdl, avfoundation, etc.)
  • noDisplay: Disable video rendering (audio only)

Input Options​

  • noControl: Disable device control
  • stayAwake: Keep device awake
  • showTouches: Show touches on device
  • powerOffOnClose: Power off device when closing

Audio Options​

  • noAudio: Disable audio
  • audioBitRate: Audio bitrate
  • audioBuffer: Audio buffer size in milliseconds

Usage Examples​

Start Basic Mirroring​

curl -X POST http://localhost:3001/api/scrcpy/start \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "emulator-5554"
  }'

Start High Quality Mirroring​

curl -X POST http://localhost:3001/api/scrcpy/start \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "emulator-5554",
    "options": {
      "maxSize": 1440,
      "bitRate": 16000000,
      "maxFps": 60,
      "showTouches": true,
      "stayAwake": true
    }
  }'

Check Status​

curl http://localhost:3001/api/scrcpy/status/emulator-5554

Stop Mirroring​

curl -X POST http://localhost:3001/api/scrcpy/stop \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "emulator-5554"
  }'

Troubleshooting​

Common Issues​

Connection Failed​

  • Ensure device is connected via USB
  • Enable USB debugging in developer options
  • Try restarting ADB: adb kill-server && adb start-server

Video Not Showing​

  • Check if scrcpy is installed and in PATH
  • Verify device screen is unlocked
  • Try different video options (lower bitrate/fps)

Audio Issues​

  • Check audio permissions on device
  • Try disabling audio: "noAudio": true
  • Verify audio drivers on host machine

Performance Issues​

  • Lower maxFps and bitRate for slower connections
  • Use maxSize to reduce resolution
  • Close other mirroring sessions

Performance Tuning​

For Slow Networks​

{
  "maxSize": 720,
  "bitRate": 2000000,
  "maxFps": 30
}

For Local Networks​

{
  "maxSize": 1440,
  "bitRate": 16000000,
  "maxFps": 60
}

For Battery Preservation​

{
  "maxSize": 1080,
  "bitRate": 4000000,
  "maxFps": 30,
  "stayAwake": false
}