docs: improve documentation and add troubleshooting guide#99
docs: improve documentation and add troubleshooting guide#99Godzilla675 wants to merge 2 commits intomainfrom
Conversation
- Added docs/troubleshooting.md covering FFmpeg, MCP, and LLM issues. - Updated docs/README.md to include troubleshooting and remove broken links. - Updated docs/development.md with contribution guidelines and monorepo tips. - Enhanced docs/api.md with Project JSON and WebSocket payload examples. - Added troubleshooting link to root README.md.
Summary of ChangesHello @Godzilla675, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the project's documentation, making it more accessible and informative for both users and potential contributors. It introduces a dedicated troubleshooting guide to assist with common problems, clarifies contribution processes, and enriches the API documentation with practical examples. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly improves the project's documentation by adding a new troubleshooting guide, contribution guidelines, and detailed API examples. The changes are well-structured and will be very helpful for developers. I've found a couple of minor areas for improvement in the new documentation to enhance clarity and correctness. Specifically, one of the JSON examples in the API documentation is technically invalid, and a troubleshooting step could be more specific about how to apply the suggested solution. Overall, this is a great contribution to the project's usability.
docs/api.md
Outdated
| { | ||
| "type": "project.updated", | ||
| "payload": { | ||
| "project": { ... } // Full project object |
There was a problem hiding this comment.
The comment // Full project object makes this JSON example invalid, as JSON does not support comments. To keep the example clear and valid, it's better to remove the comment. The { ... } notation is generally understood as a placeholder for a full object in documentation.
| "project": { ... } // Full project object | |
| "project": { ... } |
docs/troubleshooting.md
Outdated
| **Solution**: | ||
| - Complex operations like `transcribe_audio` or `render_video` can take time. | ||
| - Check system resources (CPU/RAM). | ||
| - Increase the timeout in `apps/backend/src/mcp/client-manager.ts` if necessary. |
There was a problem hiding this comment.
This is a helpful suggestion, but it's not clear from the code in apps/backend/src/mcp/client-manager.ts how to increase the timeout. The file doesn't seem to contain a configurable timeout setting for tool execution. To make this guide more actionable, could you either point to the specific location of the timeout setting or consider adding one? For example, if the underlying SDK supports it, a timeout could be passed to client.callTool.
There was a problem hiding this comment.
Pull request overview
Improves the project’s documentation set by adding a troubleshooting guide and expanding/clarifying developer and API documentation to make setup and WebSocket usage easier to navigate.
Changes:
- Added a new
docs/troubleshooting.mdguide and linked it from the root README and docs index. - Added contribution guidelines to
docs/development.md. - Expanded
docs/api.mdwith concrete examples for Project JSON and WebSocket payloads.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/troubleshooting.md | New troubleshooting guide for common setup/runtime issues. |
| docs/development.md | Adds a “Contributing” section with workflow and monorepo tips. |
| docs/api.md | Adds example Project JSON and WebSocket message payloads. |
| docs/README.md | Adds troubleshooting link to docs navigation; removes outdated quick link. |
| README.md | Adds a Troubleshooting section linking to the new guide. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/troubleshooting.md
Outdated
| **Symptoms**: LLM reports a timeout or the backend logs show "Tool execution timed out". | ||
| **Solution**: | ||
| - Complex operations like `transcribe_audio` or `render_video` can take time. | ||
| - Check system resources (CPU/RAM). | ||
| - Increase the timeout in `apps/backend/src/mcp/client-manager.ts` if necessary. |
There was a problem hiding this comment.
This section references a backend log message ("Tool execution timed out") and suggests increasing a timeout in apps/backend/src/mcp/client-manager.ts, but there is no timeout configuration there and that log string doesn’t appear in the codebase. Also, render_video doesn’t appear to be a tool name (the FFmpeg server docs list export_project instead). Please update the troubleshooting steps to reflect the actual error surfaces/tools used in this repo.
| **Symptoms**: LLM reports a timeout or the backend logs show "Tool execution timed out". | |
| **Solution**: | |
| - Complex operations like `transcribe_audio` or `render_video` can take time. | |
| - Check system resources (CPU/RAM). | |
| - Increase the timeout in `apps/backend/src/mcp/client-manager.ts` if necessary. | |
| **Symptoms**: The LLM or MCP client reports that a tool call took too long or failed due to a timeout. | |
| **Solution**: | |
| - Complex operations like `transcribe_audio` or the FFmpeg server's `export_project` can take a long time, especially on large or high‑resolution videos. | |
| - Check system resources (CPU/RAM/disk I/O) and ensure the MCP servers (e.g., FFmpeg, Whisper) are running and responsive. | |
| - Review your LLM/client or deployment configuration for any tool/HTTP/WebSocket timeout settings and increase them if long‑running operations are expected. |
docs/api.md
Outdated
| "duration": 10, | ||
| "sourceStart": 0, | ||
| "sourceEnd": 10, | ||
| "transform": { "x": 0, "y": 0, "scale": 1, "rotation": 0 } |
There was a problem hiding this comment.
The Project JSON example doesn’t match the Clip shape used in @ai-video-editor/shared-types: effects is a required array field on clips. To keep the example copy/pasteable and accurate, include "effects": [] (and any other required fields) in the clip object.
| "transform": { "x": 0, "y": 0, "scale": 1, "rotation": 0 } | |
| "transform": { "x": 0, "y": 0, "scale": 1, "rotation": 0 }, | |
| "effects": [] |
| "type": "project.updated", | ||
| "payload": { | ||
| "project": { ... } // Full project object | ||
| } |
There was a problem hiding this comment.
This code block is labeled as JSON, but it contains a // comment ("project": { ... } // ...), which makes it invalid JSON for users who copy/paste it. Consider removing the inline comment or changing the fence to jsonc and/or moving the explanation outside the block.
docs/api.md
Outdated
| "type": "copilot.message", | ||
| "payload": { | ||
| "content": "Add a 5 second clip of the sunset to the start of the video", | ||
| "projectId": "550e8400-e29b-41d4-a716-446655440000" |
There was a problem hiding this comment.
copilot.message payloads in the actual frontend/backend also support fields like model and projectData (the backend destructures them and the web app sends them). The example here currently omits them, which can make it harder to reproduce requests during debugging; consider documenting these as optional fields or including them in the example.
| "projectId": "550e8400-e29b-41d4-a716-446655440000" | |
| "projectId": "550e8400-e29b-41d4-a716-446655440000", | |
| "model": "gpt-4o-mini", // optional: model to use for this request | |
| "projectData": { ... } // optional: serialized project snapshot for context |
|
@copilot open a new pull request to apply changes based on the comments in this thread |
|
@Godzilla675 I've opened a new pull request, #100, to work on those changes. Once the pull request is ready, I'll request review from you. |
I've applied the requested changes based on the review thread:
|
- docs/api.md: Fix invalid JSON by removing comments, adding missing 'effects' field, and including optional 'model'/'projectData' fields. - docs/troubleshooting.md: Correct tool name to 'export_project' and update timeout advice for better accuracy.
This PR improves the project documentation by:
PR created automatically by Jules for task 11858702151210839129 started by @Godzilla675