update to transcribe media and fixing to documentation

docs/code/execute/execute_python.md

@@ -2,7 +2,7 @@
 
 ## 1. Overview
 
-The `/v1/code/execute/python` endpoint allows users to execute Python code on the server. This endpoint is part of the `v1` API and is registered in the `app.py` file. It is designed to provide a secure and controlled environment for executing Python code, with features like input validation, timeout handling, and output capturing.
+The `/v1/code/execute/python` endpoint allows users to execute Python code on the server. This endpoint is part of the version 1.0 API structure defined in `app.py`. It is designed to provide a secure and controlled environment for executing Python code, with features like input validation, output capturing, and timeout handling.
 
 ## 2. Endpoint
 
@@ -24,7 +24,7 @@ The request body must be a JSON object with the following properties:
 - `webhook_url` (string, optional): The URL to receive the execution result via a webhook.
 - `id` (string, optional): A unique identifier for the request.
 
-The `validate_payload` decorator in the routes file enforces the following JSON schema for the request body:
+The `validate_payload` directive in the routes file enforces the following JSON schema for the request body:
 
 ```json
 {
@@ -42,6 +42,8 @@ The `validate_payload` decorator in the routes file enforces the following JSON
 
 ### Example Request
 
+**Request Payload:**
+
 ```json
 {
     "code": "print('Hello, World!')",
@@ -51,6 +53,8 @@ The `validate_payload` decorator in the routes file enforces the following JSON
 }
 ```
 
+**cURL Command:**
+
 ```bash
 curl -X POST \
      -H "x-api-key: YOUR_API_KEY" \
@@ -67,6 +71,7 @@ The success response follows the general response format defined in `app.py`. He
 
 ```json
 {
+    "endpoint": "/v1/code/execute/python",
     "code": 200,
     "id": "unique-request-id",
     "job_id": "generated-job-id",
@@ -77,8 +82,8 @@ The success response follows the general response format defined in `app.py`. He
         "exit_code": 0
     },
     "message": "success",
-    "pid": 1234,
-    "queue_id": 12345678,
+    "pid": 12345,
+    "queue_id": 1234567890,
     "run_time": 0.123,
     "queue_time": 0.0,
     "total_time": 0.123,
@@ -89,45 +94,81 @@ The success response follows the general response format defined in `app.py`. He
 
 ### Error Responses
 
-- **400 Bad Request**:
-  - Example: `{"error": "Execution failed", "stdout": "", "exit_code": 1}`
-  - Reason: The Python code execution failed, or there was an error in the user's code.
+#### Missing or Invalid Parameters
+
+**Status Code:** 400 Bad Request
+
+```json
+{
+    "error": "Missing or invalid parameters",
+    "stdout": "",
+    "exit_code": 400
+}
+```
+
+#### Execution Error
 
-- **408 Request Timeout**:
-  - Example: `{"error": "Execution timed out after 10 seconds"}`
-  - Reason: The Python code execution exceeded the specified timeout.
+**Status Code:** 400 Bad Request
+
+```json
+{
+    "error": "Error message from the executed code",
+    "stdout": "Output from the executed code",
+    "exit_code": 400
+}
+```
 
-- **500 Internal Server Error**:
-  - Example: `{"error": "Failed to parse execution result"}`
-  - Reason: An internal error occurred while parsing the execution result.
+#### Execution Timeout
+
+**Status Code:** 408 Request Timeout
+
+```json
+{
+    "error": "Execution timed out after 10 seconds"
+}
+```
+
+#### Internal Server Error
+
+**Status Code:** 500 Internal Server Error
+
+```json
+{
+    "error": "An internal server error occurred",
+    "stdout": "",
+    "stderr": "",
+    "exit_code": 500
+}
+```
 
 ## 5. Error Handling
 
-The endpoint handles the following common errors:
+The endpoint handles various types of errors, including:
 
-- **Missing or invalid parameters**: If the request body is missing or contains invalid parameters, a `400 Bad Request` error is returned.
-- **Execution timeout**: If the Python code execution exceeds the specified timeout, a `408 Request Timeout` error is returned.
-- **Internal errors**: If an internal error occurs during code execution or result parsing, a `500 Internal Server Error` is returned.
+- Missing or invalid parameters (400 Bad Request)
+- Execution errors, such as syntax errors or exceptions (400 Bad Request)
+- Execution timeout (408 Request Timeout)
+- Internal server errors (500 Internal Server Error)
 
-Additionally, the main application context (`app.py`) includes error handling for queue overload. If the maximum queue length is reached, a `429 Too Many Requests` error is returned.
+The main application context (`app.py`) also includes error handling for queue overload (429 Too Many Requests) and other general errors.
 
 ## 6. Usage Notes
 
-- The Python code is executed in a sandboxed environment, with limited access to system resources and libraries.
-- The execution output (stdout and stderr) is captured and included in the response.
-- The return value of the executed code is included in the response if the execution is successful.
-- The `webhook_url` parameter is optional and can be used to receive the execution result via a webhook.
+- The executed code runs in a sandboxed environment, with limited access to system resources.
+- The code execution is limited to a maximum of 300 seconds (5 minutes) by default, but this can be adjusted using the `timeout` parameter.
+- The execution result, including stdout, stderr, and the return value, is captured and returned in the response.
+- If a `webhook_url` is provided, the execution result will also be sent to the specified webhook.
 
 ## 7. Common Issues
 
-- **Syntax errors or exceptions in the user's code**: These will result in a `400 Bad Request` error, with the error message and traceback included in the response.
-- **Infinite loops or long-running code**: The execution will be terminated after the specified timeout, resulting in a `408 Request Timeout` error.
-- **Excessive resource usage**: The sandboxed environment may impose limits on memory, CPU, or other resources, which could cause the execution to fail.
+- Attempting to execute code that accesses restricted resources or performs disallowed operations may result in an execution error.
+- Long-running or resource-intensive code may trigger the execution timeout.
+- Providing an invalid `webhook_url` will prevent the execution result from being delivered to the specified webhook.
 
 ## 8. Best Practices
 
-- **Validate user input**: Always validate and sanitize user input to prevent code injection or other security vulnerabilities.
-- **Set appropriate timeouts**: Choose a reasonable timeout value based on the expected complexity of the code to be executed.
-- **Monitor resource usage**: Keep an eye on the resource usage of the execution environment to prevent excessive consumption or denial of service attacks.
-- **Implement rate limiting**: Consider implementing rate limiting to prevent abuse or overload of the endpoint.
-- **Log and monitor errors**: Ensure that errors are properly logged and monitored for debugging and security purposes.
+- Always validate and sanitize user input to prevent code injection attacks.
+- Set an appropriate timeout value based on the expected execution time of the code.
+- Monitor the execution logs for any errors or unexpected behavior.
+- Implement rate limiting or queue management to prevent abuse or overload of the endpoint.
+- Consider implementing additional security measures, such as code sandboxing or whitelisting/blacklisting certain operations or modules.

docs/ffmpeg/ffmpeg_compose.md

@@ -2,12 +2,12 @@
 
 ## 1. Overview
 
-The `/v1/ffmpeg/compose` endpoint is a part of the Flask API application and is designed to provide a flexible and powerful way to compose and manipulate media files using FFmpeg. This endpoint allows users to specify input files, filters, and output options, enabling a wide range of media processing tasks such as transcoding, concatenation, and video editing.
+The `/v1/ffmpeg/compose` endpoint is a flexible and powerful API that allows users to compose complex FFmpeg commands by providing input files, filters, and output options. This endpoint is part of the version 1.0 API structure, as shown in the `app.py` file. It is designed to handle various media processing tasks, such as video and audio manipulation, transcoding, and more.
 
 ## 2. Endpoint
 
-- **URL Path**: `/v1/ffmpeg/compose`
-- **HTTP Method**: `POST`
+**URL Path:** `/v1/ffmpeg/compose`
+**HTTP Method:** `POST`
 
 ## 3. Request
 
@@ -21,25 +21,25 @@ The request body should be a JSON object with the following properties:
 
 - `inputs` (required, array): An array of input file objects, each containing:
   - `file_url` (required, string): The URL of the input file.
-  - `options` (optional, array): An array of input file options, each containing:
-    - `option` (required, string): The FFmpeg option to apply.
+  - `options` (optional, array): An array of option objects, each containing:
+    - `option` (required, string): The FFmpeg option.
     - `argument` (optional, string, number, or null): The argument for the option.
 - `filters` (optional, array): An array of filter objects, each containing:
-  - `filter` (required, string): The FFmpeg filter to apply.
-- `outputs` (required, array): An array of output file objects, each containing:
-  - `options` (required, array): An array of output file options, each containing:
-    - `option` (required, string): The FFmpeg option to apply.
+  - `filter` (required, string): The FFmpeg filter.
+- `outputs` (required, array): An array of output option objects, each containing:
+  - `options` (required, array): An array of option objects, each containing:
+    - `option` (required, string): The FFmpeg option.
     - `argument` (optional, string, number, or null): The argument for the option.
 - `global_options` (optional, array): An array of global option objects, each containing:
-  - `option` (required, string): The FFmpeg global option to apply.
+  - `option` (required, string): The FFmpeg global option.
   - `argument` (optional, string, number, or null): The argument for the option.
 - `metadata` (optional, object): An object specifying which metadata to include in the response, with the following properties:
   - `thumbnail` (optional, boolean): Whether to include a thumbnail for the output file.
   - `filesize` (optional, boolean): Whether to include the file size of the output file.
   - `duration` (optional, boolean): Whether to include the duration of the output file.
   - `bitrate` (optional, boolean): Whether to include the bitrate of the output file.
   - `encoder` (optional, boolean): Whether to include the encoder used for the output file.
-- `webhook_url` (required, string): The URL to send the response to.
+- `webhook_url` (required, string): The URL to send the response webhook.
 - `id` (required, string): A unique identifier for the request.
 
 ### Example Request
@@ -66,7 +66,7 @@ The request body should be a JSON object with the following properties:
   ],
   "filters": [
     {
-      "filter": "scale=640:480"
+      "filter": "hflip"
     }
   ],
   "outputs": [
@@ -126,7 +126,7 @@ curl -X POST \
     ],
     "filters": [
       {
-        "filter": "scale=640:480"
+        "filter": "hflip"
       }
     ],
     "outputs": [
@@ -166,23 +166,23 @@ curl -X POST \
 
 The response will be sent to the specified `webhook_url` as a JSON object with the following properties:
 
-- `endpoint` (string): The endpoint that processed the request (`/v1/ffmpeg/compose`).
+- `endpoint` (string): The endpoint URL (`/v1/ffmpeg/compose`).
 - `code` (number): The HTTP status code (200 for success).
 - `id` (string): The unique identifier for the request.
 - `job_id` (string): The unique job ID assigned to the request.
 - `response` (array): An array of output file objects, each containing:
   - `file_url` (string): The URL of the uploaded output file.
   - `thumbnail_url` (string, optional): The URL of the uploaded thumbnail, if requested.
-  - `filesize` (number, optional): The size of the output file in bytes, if requested.
-  - `duration` (number, optional): The duration of the output file in seconds, if requested.
-  - `bitrate` (number, optional): The bitrate of the output file in bits per second, if requested.
+  - `filesize` (number, optional): The file size of the output file, if requested.
+  - `duration` (number, optional): The duration of the output file, if requested.
+  - `bitrate` (number, optional): The bitrate of the output file, if requested.
   - `encoder` (string, optional): The encoder used for the output file, if requested.
-- `message` (string): A success message (`"success"`).
+- `message` (string): The success message ("success").
 - `pid` (number): The process ID of the worker that processed the request.
 - `queue_id` (number): The ID of the queue used for processing the request.
-- `run_time` (number): The time taken to process the request, in seconds.
-- `queue_time` (number): The time the request spent in the queue, in seconds.
-- `total_time` (number): The total time taken to process the request, including queue time, in seconds.
+- `run_time` (number): The time taken to process the request (in seconds).
+- `queue_time` (number): The time the request spent in the queue (in seconds).
+- `total_time` (number): The total time taken to process the request, including queue time (in seconds).
 - `queue_length` (number): The current length of the processing queue.
 - `build_number` (string): The build number of the application.
 
@@ -193,12 +193,18 @@ The response will be sent to the specified `webhook_url` as a JSON object with t
 - **429 Too Many Requests**: The maximum queue length has been reached.
 - **500 Internal Server Error**: An unexpected error occurred while processing the request.
 
-Example error response (400 Bad Request):
+Example error response:
 
 ```json
 {
   "code": 400,
-  "message": "Invalid request payload: 'inputs' is a required property"
+  "id": "unique-request-id",
+  "job_id": "job-id",
+  "message": "Invalid request payload: 'inputs' is a required property",
+  "pid": 123,
+  "queue_id": 456,
+  "queue_length": 0,
+  "build_number": "1.0.0"
 }
 ```
 
@@ -209,32 +215,31 @@ The API handles various types of errors, including:
 - **Missing or invalid parameters**: If the request payload is missing required parameters or contains invalid data types, a 400 Bad Request error will be returned.
 - **Authentication failure**: If the provided API key is invalid or missing, a 401 Unauthorized error will be returned.
 - **Queue limit reached**: If the maximum queue length is reached, a 429 Too Many Requests error will be returned.
-- **Unexpected errors**: If an unexpected error occurs during request processing, a 500 Internal Server Error will be returned, along with an error message.
+- **Unexpected errors**: If an unexpected error occurs during request processing, a 500 Internal Server Error will be returned.
 
 The main application context (`app.py`) includes error handling for the processing queue. If the maximum queue length is set and the queue size reaches that limit, new requests will be rejected with a 429 Too Many Requests error.
 
 ## 6. Usage Notes
 
-- The `inputs` array can contain multiple input files, allowing for operations like concatenation or merging.
-- The `filters` array allows applying FFmpeg filters to the input files.
-- The `outputs` array specifies the output file options, such as codec, bitrate, and resolution.
-- The `global_options` array allows setting global FFmpeg options that apply to the entire operation.
-- The `metadata` object allows requesting specific metadata to be included in the response, such as thumbnail, file size, duration, bitrate, and encoder information.
-- The `webhook_url` parameter is required, and the response will be sent to this URL as a POST request.
-- The `id` parameter is a unique identifier for the request, which can be used for tracking and logging purposes.
+- The `inputs` array must contain at least one input file object.
+- The `outputs` array must contain at least one output option object.
+- The `filters` array is optional and can be used to apply FFmpeg filters to the input files.
+- The `global_options` array is optional and can be used to specify global FFmpeg options.
+- The `metadata` object is optional and can be used to request specific metadata for the output files.
+- The `webhook_url` parameter is required and specifies the URL where the response should be sent.
+- The `id` parameter is required and should be a unique identifier for the request.
 
 ## 7. Common Issues
 
 - Providing invalid or malformed input file URLs.
 - Specifying invalid or unsupported FFmpeg options or filters.
-- Attempting to process large or high-resolution files, which may result in long processing times or queue delays.
-- Reaching the maximum queue length, which will cause new requests to be rejected.
+- Reaching the maximum queue length, resulting in a 429 Too Many Requests error.
+- Network or connectivity issues that prevent the response webhook from being delivered.
 
 ## 8. Best Practices
 
-- Validate input file URLs and ensure they are accessible before submitting the request.
-- Test FFmpeg options and filters with sample files before using them in production.
-- Consider transcoding or downscaling large or high-resolution files to reduce processing time and queue delays.
-- Monitor the queue length and adjust the maximum queue length as needed to prevent excessive queuing or request rejections.
-- Implement retry mechanisms for failed requests or requests that encounter queue limits.
-- Use the `id` parameter to track and correlate requests with responses for better logging and debugging.
+- Validate input file URLs and ensure they are accessible before sending the request.
+- Test your FFmpeg command locally before using the API to ensure it works as expected.
+- Monitor the queue length and adjust the maximum queue length as needed to prevent overloading the system.
+- Implement retry mechanisms for handling failed webhook deliveries or other transient errors.
+- Use unique and descriptive `id` values for each request to aid in troubleshooting and monitoring.