sjs/Peekaboo
1
0
Fork 0
mirror of https://github.com/samsonjs/Peekaboo.git synced 2026-03-25 09:25:47 +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.
**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:**
```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.
* `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.
* `"png"` or `"jpg"`: Saves the image to the specified `path` in the chosen format. If `path` is not provided, this behaves like `"data"`.
* `"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`.
* `"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`. **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"`.
* `capture_focus` (string, optional, default: `"background"`): Controls window focus behavior during capture.
* `"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(
"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. " +
"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. " +
"The tool will automatically fall back to PNG format for screen captures."
"For application window captures: If 'path' is not given, 'format' defaults to 'data' behavior (inline PNG data returned). " +
"For screen captures: Cannot use 'data' format due to large image sizes causing JavaScript stack overflow. " +
"Screen captures always save to files (temp directory if no path specified) with automatic PNG format fallback."
),
capture_focus: z.enum(["background", "foreground"])
.optional().default("background").describe(