sjs/Peekaboo
1
0
Fork 0
mirror of https://github.com/samsonjs/Peekaboo.git synced 2026-04-27 15:07:41 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Clarify format parameter behavior for screen vs app captures

Browse source 
- Update README.md to clearly explain that screen captures cannot use format: "data"
- Clarify that screen captures always save to files (temp or specified path)
- Update spec.md to distinguish behavior between app window captures and screen captures
- Make it clear that empty format string defaults to PNG file format for screen captures
- Address confusion where documentation suggested format defaults to "data" when path not given

This resolves the apparent contradiction between documentation and actual behavior
shown in the test screenshot where format: "" resulted in file saving rather than
data format for a screen capture.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Peter Steinberger 2025-06-08 07:37:50 +01:00
parent 9837e7bea8
commit d8a0e10b02
2 changed files with 6 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
README.md
View file

@ -291,7 +291,7 @@ Peekaboo provides three main tools for AI agents:
Captures macOS screen content with automatic shadow/frame removal. Captures macOS screen content with automatic shadow/frame removal.
**Important:** Screen captures with `format: "data"` automatically fall back to PNG format due to the large size of screen images causing JavaScript stack overflow errors. When this happens, the tool saves the image to a file and includes a warning message explaining the fallback. **Important:** Screen captures **cannot use `format: "data"`** due to the large size of screen images causing JavaScript stack overflow errors. Screen captures always save to files, either to a specified path or a temporary directory. When `format: "data"` is requested for screen captures, the tool automatically falls back to PNG format and saves to a file with a warning message explaining the fallback.
**Examples:** **Examples:**
```javascript ```javascript
@ -544,8 +544,8 @@ Captures macOS screen content and optionally analyzes it. Window shadows/frames
* `path` (string, optional): Base absolute path for saving the captured image(s). If `format` is `"data"` and `path` is also provided, the image is saved to this path (as a PNG) AND Base64 data is returned. If a `question` is provided and `path` is omitted, a temporary path is used for capture, and the file is deleted after analysis. * `path` (string, optional): Base absolute path for saving the captured image(s). If `format` is `"data"` and `path` is also provided, the image is saved to this path (as a PNG) AND Base64 data is returned. If a `question` is provided and `path` is omitted, a temporary path is used for capture, and the file is deleted after analysis.
* `question` (string, optional): If provided, the captured image will be analyzed. The server automatically selects an AI provider from those configured in the `PEEKABOO_AI_PROVIDERS` environment variable. * `question` (string, optional): If provided, the captured image will be analyzed. The server automatically selects an AI provider from those configured in the `PEEKABOO_AI_PROVIDERS` environment variable.
* `format` (string, optional, default: `"png"`): Specifies the output image format or data return type. * `format` (string, optional, default: `"png"`): Specifies the output image format or data return type.
* `"png"` or `"jpg"`: Saves the image to the specified `path` in the chosen format. If `path` is not provided, this behaves like `"data"`. * `"png"` or `"jpg"`: Saves the image to the specified `path` in the chosen format. For application captures: if `path` is not provided, behaves like `"data"`. For screen captures: always saves to file.
* `"data"`: Returns Base64 encoded PNG data of the image directly in the MCP response. If `path` is also specified, a PNG file is also saved to that `path`. * `"data"`: Returns Base64 encoded PNG data of the image directly in the MCP response. If `path` is also specified, a PNG file is also saved to that `path`. **Note: Screen captures cannot use this format and will automatically fall back to PNG file format.**
* Invalid values (empty strings, null, or unrecognized formats) automatically fall back to `"png"`. * Invalid values (empty strings, null, or unrecognized formats) automatically fall back to `"png"`.
* `capture_focus` (string, optional, default: `"background"`): Controls window focus behavior during capture. * `capture_focus` (string, optional, default: `"background"`): Controls window focus behavior during capture.
* `"background"`: Captures without altering the current window focus (default). * `"background"`: Captures without altering the current window focus (default).

6
docs/spec.md
View file

@ -145,9 +145,9 @@ Configured AI Providers (from PEEKABOO_AI_PROVIDERS ENV): <parsed list or 'None
format: z.enum(["png", "jpg", "data"]).optional().default("png").describe( format: z.enum(["png", "jpg", "data"]).optional().default("png").describe(
"Output format. 'png' or 'jpg' save to 'path' (if provided). " + "Output format. 'png' or 'jpg' save to 'path' (if provided). " +
"'data' returns Base64 encoded PNG data inline; if 'path' is also given, saves a PNG file to 'path' too. " + "'data' returns Base64 encoded PNG data inline; if 'path' is also given, saves a PNG file to 'path' too. " +
"If 'path' is not given, 'format' defaults to 'data' behavior (inline PNG data returned). " + "For application window captures: If 'path' is not given, 'format' defaults to 'data' behavior (inline PNG data returned). " +
"Note: Screen captures cannot use 'data' format due to large image sizes causing JavaScript stack overflow. " + "For screen captures: Cannot use 'data' format due to large image sizes causing JavaScript stack overflow. " +
"The tool will automatically fall back to PNG format for screen captures." "Screen captures always save to files (temp directory if no path specified) with automatic PNG format fallback."
), ),
capture_focus: z.enum(["background", "foreground"]) capture_focus: z.enum(["background", "foreground"])
.optional().default("background").describe( .optional().default("background").describe(