Android Puppeteer

Instructions

Implementation Reference

• puppeteer.py:1067-1182 (handler)

  The primary handler function for the 'record_video' MCP tool. Decorated with @mcp.tool(), it registers the tool and implements the logic to start video recording of an Android device screen using scrcpy. It handles filename generation, process management, and tracks active recordings via a global dictionary.

  async def record_video(device_id: str = None, filename: str = None, resolution: str = None, bitrate: str = "8M") -> dict:
      """Start recording a video using scrcpy. The video will be saved to the videos directory."""
      try:
          # Use android-puppeteer/videos directory for video recordings
          current_dir = os.path.dirname(os.path.abspath(__file__))
          videos_dir = os.path.join(current_dir, "videos")
          os.makedirs(videos_dir, exist_ok=True)
  
          # Generate filename if not provided
          if filename:
              # Ensure it has .mp4 extension
              if not filename.endswith('.mp4'):
                  filename = f"{filename}.mp4"
          else:
              # Use timestamp if no filename provided
              timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
              filename = f"recording_{timestamp}.mp4"
  
          filepath = os.path.join(videos_dir, filename)
  
          # Create recording key for tracking
          recording_key = device_id or "default"
  
          # Check if already recording for this device
          if recording_key in active_recordings:
              return {
                  "success": False,
                  "error": f"Already recording for device {recording_key}. Stop the current recording first.",
                  "device_id": device_id or "default"
              }
  
          # Build scrcpy command for recording
          cmd = ['scrcpy']
  
          # Add device selection if specified
          if device_id:
              cmd.extend(['-s', device_id])
  
          # Add recording parameters
          cmd.extend(['--record', filepath])
  
          # Add video quality parameters
          cmd.extend(['--video-bit-rate', bitrate])
  
          if resolution:
              cmd.extend(['--max-size', resolution])
  
          # Add minimal parameters for recording
          cmd.extend([
              '--no-playback'  # Don't show the device screen (updated flag for scrcpy v3.2+)
          ])
  
          # Start the recording process
          process = subprocess.Popen(
              cmd,
              stdout=subprocess.PIPE,
              stderr=subprocess.PIPE,
              preexec_fn=os.setsid  # Create new process group for proper termination
          )
  
          # Give the process a moment to start and check if it's still running
          import time
          time.sleep(1)
  
          # Check if process started successfully
          if process.poll() is not None:
              # Process terminated immediately, capture error output
              stderr_output = process.stderr.read().decode() if process.stderr else ""
              stdout_output = process.stdout.read().decode() if process.stdout else ""
              return {
                  "success": False,
                  "error": f"scrcpy process terminated immediately. stderr: {stderr_output}, stdout: {stdout_output}",
                  "filepath": None,
                  "command": ' '.join(cmd)
              }
  
          # Store the process for later termination
          active_recordings[recording_key] = {
              "process": process,
              "filepath": filepath,
              "filename": filename,
              "start_time": datetime.now(),
              "device_id": device_id or "default"
          }
  
          return {
              "success": True,
              "message": f"Video recording started successfully",
              "filepath": filepath,
              "filename": filename,
              "device_id": device_id or "default",
              "recording_key": recording_key,
              "bitrate": bitrate,
              "resolution": resolution,
              "process_id": process.pid
          }
  
      except FileNotFoundError:
          return {
              "success": False,
              "error": "scrcpy not found. Please ensure scrcpy is installed and in PATH.",
              "filepath": None
          }
      except PermissionError:
          return {
              "success": False,
              "error": f"Permission denied: Cannot create directory or write to {videos_dir}",
              "filepath": None
          }
      except Exception as e:
          return {
              "success": False,
              "error": f"Unexpected error starting recording: {e}",
              "filepath": None
          }