Upload 131 files

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,70 @@
+name: Bug Report
+title: "[Bug]: "
+labels: ["bug"]
+description: Report broken or incorrect behaviour
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Thanks for taking the time to fill out a bug.
+        Please note that this form is for bugs only!
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Reproduction Steps
+      description: >
+         What you did to make it happen. Include any request payloads, API calls, or specific commands used.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Expected behavior
+      description: >
+         A clear and concise description of what you expected to happen.
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Screenshots and relevant files
+      description: >
+         If applicable, add screenshots or relevant files to help explain your problem.
+    validations:
+      required: false
+  - type: dropdown
+    id: platform
+    attributes:
+      label: "Platform"
+      description: "Select the platform where you encountered this bug"
+      options:
+        - "Google Cloud Platform"
+        - "Digital Ocean"
+        - "Local"
+        - "Other"
+    validations:
+      required: true
+  - type: dropdown
+    id: assign
+    attributes:
+      label: "Would you like to work on this issue?"
+      options:
+        - "Yes"
+  - type: checkboxes
+    attributes:
+      label: Checklist
+      description: >
+        Let's make sure you've properly done due diligence when reporting this issue!
+      options:
+        - label: I have searched the open issues for duplicates.
+          required: true
+        - label: I have shown the entire traceback, if possible.
+          required: true
+  - type: textarea
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,7 @@
+contact_links:
+  - name: Help or Questions?
+    url: https://www.skool.com/no-code-architects/about?ref=2f302c52a77541efa2dd5e8b27f3f8c9
+    about: Get courses, community, support daily calls and more.
+
+blank_issues_enabled: true
+# Allow blank issues for now?

.github/workflows/update-build-number.yml

@@ -0,0 +1,37 @@
+name: Update Build Number
+on:
+  push:
+    branches:
+      - build
+permissions:
+  contents: write
+jobs:
+  update-build-number:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.ACTION_BYPASS }}
+      
+      - name: Update build number
+        run: |
+          if [ ! -f build_number.txt ]; then
+            echo "0" > build_number.txt
+          fi
+          build_number=$(( $(cat build_number.txt) + 1 ))
+          echo $build_number > build_number.txt
+          
+          # Update the version in your code file (e.g., version.py)
+          echo "BUILD_NUMBER = $build_number" > version.py
+          
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+          git add build_number.txt version.py
+          git commit -m "Build $build_number: Bump build number [skip ci]"
+          git push origin build
+
+      - name: Push changes to testing branch
+        run: |
+          git push origin build:testing --force

LICENSE

@@ -0,0 +1,340 @@
+Copyright (c) 2025 Stephen G. Pope
+
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Moe Ghoul>, 1 April 1989
+  Moe Ghoul, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.

docker-compose.md

@@ -0,0 +1,200 @@
+# Install No Code Architect Toolkit with Docker
+
+Installation of No Code Architect Toolkit with Docker offers the following advantages:
+- Install No Code Architect Toolkit in a clean environment.
+- Simplify the setup process.
+- Avoid compatibility issues across different operating systems with Docker's consistent environment.
+
+> **Info**  
+> If your domain/subdomain is already pointed to the server, start at step 2.  
+> If you have already installed Docker and Docker-Compose, start at step 3.
+
+---
+
+## 1. DNS Setup
+
+Point your domain/subdomain to the server. Add an A record to route the domain/subdomain accordingly:
+
+- **Type**: A  
+- **Name**: The desired domain/subdomain  
+- **IP Address**: `<IP_OF_YOUR_SERVER>`  
+
+---
+
+## 2. Install Docker
+
+This can vary depending on the Linux distribution used. Below are instructions for Ubuntu:
+
+### Set up Docker's APT Repository
+
+```bash
+# Add Docker's official GPG key:
+sudo apt-get update
+sudo apt-get install ca-certificates curl
+sudo install -m 0755 -d /etc/apt/keyrings
+sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
+sudo chmod a+r /etc/apt/keyrings/docker.asc
+
+# Add the repository to APT sources:
+echo \
+"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
+$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
+sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+sudo apt-get update
+```
+
+### Install the Docker Packages
+
+```bash
+sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+```
+
+---
+
+## 3. Create Docker Compose File
+
+Create a `docker-compose.yml` file and paste the following configuration:
+
+### With SSL Support
+Enables SSL/TLS for secure, encrypted communications. Ideal for those wanting a hands-off approach to SSL setup.
+
+```yaml
+services:
+  traefik:
+    image: "traefik"
+    restart: unless-stopped
+    command:
+      - "--api=true"
+      - "--api.insecure=true"
+      - "--providers.docker=true"
+      - "--providers.docker.exposedbydefault=false"
+      - "--entrypoints.web.address=:80"
+      - "--entrypoints.web.http.redirections.entryPoint.to=websecure"
+      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
+      - "--entrypoints.websecure.address=:443"
+      - "--certificatesresolvers.mytlschallenge.acme.tlschallenge=true"
+      - "--certificatesresolvers.mytlschallenge.acme.email=${SSL_EMAIL}"
+      - "--certificatesresolvers.mytlschallenge.acme.storage=/letsencrypt/acme.json"
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - traefik_data:/letsencrypt
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+  ncat:
+    image: stephengpope/no-code-architects-toolkit:latest
+    env_file:
+      - .env
+    labels:
+      - traefik.enable=true
+      - traefik.http.routers.ncat.rule=Host(`${APP_DOMAIN}`)
+      - traefik.http.routers.ncat.tls=true
+      - traefik.http.routers.ncat.entrypoints=web,websecure
+      - traefik.http.routers.ncat.tls.certresolver=mytlschallenge
+    volumes:
+      - storage:/var/www/html/storage/app
+      - logs:/var/www/html/storage/logs
+    restart: unless-stopped
+
+volumes:
+  traefik_data:
+    driver: local
+  storage:
+    driver: local
+  logs:
+    driver: local
+```
+
+---
+
+## 4. Create `.env` File
+
+Create an `.env` file and configure it accordingly:
+
+```env
+# The name of your application.
+APP_NAME=NCAToolkit
+
+# Debug mode setting. Set to `false` for production environments.
+APP_DEBUG=false
+
+# Your app's domain or subdomain, without the 'http://' or 'https://' prefix.
+APP_DOMAIN=example.com
+
+# Full application URL is automatically configured; no modification required.
+APP_URL=https://${APP_DOMAIN}
+
+# SSL settings
+SSL_EMAIL=user@example.com
+
+# API_KEY
+# Purpose: Used for API authentication.
+# Requirement: Mandatory.
+API_KEY=your_api_key_here
+
+# s3 Compatible Storage Env Vars
+#
+#S3_ACCESS_KEY=your_access_key
+#S3_SECRET_KEY=your_secret_key
+#S3_ENDPOINT_URL=https://your-endpoint-url
+#S3_REGION=your-region
+#S3_BUCKET_NAME=your-bucket-name
+
+
+# Google Cloud Storage Env Variables
+#
+# GCP_SA_CREDENTIALS
+# Purpose: The JSON credentials for the GCP Service Account.
+# Requirement: Mandatory if using GCP storage.
+#GCP_SA_CREDENTIALS=/path/to/your/gcp/service_account.json
+
+# GCP_BUCKET_NAME
+# Purpose: The name of the GCP storage bucket.
+# Requirement: Mandatory if using GCP storage.
+#GCP_BUCKET_NAME=your_gcp_bucket_name
+
+# STORAGE_PATH
+# Purpose: The base path for storage operations.
+# Default: GCP
+# Requirement: Optional.
+#STORAGE_PATH=GCP
+
+```
+
+---
+
+## 5. Start Docker Compose
+
+Start No Code Architect Toolkit  using the following command:
+
+```bash
+docker compose up -d
+```
+
+To view logs in real time:
+
+```bash
+docker compose logs -f
+```
+
+To stop the containers:
+
+```bash
+docker compose stop
+```
+
+To restart and reload env vars
+
+# First update your .env file with the correct values
+# Then run:
+
+```bash
+docker compose up -d --force-recreate ncat
+```
+
+---
+
+## 6. Done
+
+No Code Architect Toolkit is now accessible through the specified APP_URL. For example:  
+[https://example.com](https://example.com)

docs/adding_routes.md

@@ -0,0 +1,81 @@
+# Adding New Routes
+
+This document explains how to add new routes to the application using the dynamic route registration system.
+
+## Overview
+
+The application now uses a dynamic route registration system that automatically discovers and registers all Flask blueprints in the `routes` directory. This means you no longer need to manually import and register blueprints in `app.py`.
+
+## How to Add a New Route
+
+1. **Create a new route file**
+
+   Create a new Python file in the appropriate location in the `routes` directory. For a v1 API endpoint, you would typically place it in a subdirectory under `routes/v1/` based on the functionality.
+
+   For example:
+   ```
+   routes/v1/email/send_email.py
+   ```
+
+2. **Define your Blueprint**
+
+   In your route file, define a Flask Blueprint with a unique name. Make sure to follow the naming convention:
+   
+   ```python
+   # routes/v1/email/send_email.py
+   from flask import Blueprint, request
+   from services.authentication import authenticate
+   from app_utils import queue_task_wrapper
+
+   v1_email_send_bp = Blueprint('v1_email_send', __name__)
+
+   @v1_email_send_bp.route('/v1/email/send', methods=['POST'])
+   @authenticate
+   @queue_task_wrapper(bypass_queue=False)
+   def send_email(job_id, data):
+       """
+       Send an email
+       
+       Args:
+           job_id (str): Job ID assigned by queue_task_wrapper
+           data (dict): Request data containing email details
+       
+       Returns:
+           Tuple of (response_data, endpoint_string, status_code)
+       """
+       # Your implementation here
+       endpoint = "/v1/email/send"
+       
+       # Return response
+       return {"message": "Email sent"}, endpoint, 200
+   ```
+
+3. **That's it!**
+
+   No need to modify `app.py`. The blueprint will be automatically discovered and registered when the application starts.
+
+## Naming Conventions
+
+When creating new routes, please follow these naming conventions:
+
+1. **Blueprint names**: Use the format `{version}_{category}_{action}_bp`
+   - Example: `v1_email_send_bp` for sending emails
+
+2. **Route paths**: Use the format `/{version}/{category}/{action}`
+   - Example: `/v1/email/send`
+
+3. **File structure**: Place files in directories that match the route structure
+   - Example: `routes/v1/email/send_email.py`
+
+## Testing Your Route
+
+After adding your route, restart the application and your new endpoint should be available immediately.
+
+## Troubleshooting
+
+If your route isn't being registered:
+
+1. Check logs for any import errors
+2. Ensure your blueprint variable is defined at the module level
+3. Verify the blueprint name follows the naming convention
+4. Make sure your Python file is in the correct directory under `routes/` 

docs/audio/concatenate.md

@@ -0,0 +1,207 @@
+# Audio Concatenation API Endpoint Documentation
+
+## Overview
+
+The `/v1/audio/concatenate` endpoint provides functionality to combine multiple audio files into a single audio file. This endpoint is part of the v1 API structure and is registered in the main application through the `v1_audio_concatenate_bp` Blueprint. It leverages the application's queuing system to handle asynchronous processing, which is particularly useful for potentially time-consuming audio processing operations.
+
+## Endpoint
+
+- **URL**: `/v1/audio/concatenate`
+- **Method**: `POST`
+
+## Request
+
+### Headers
+
+- `x-api-key`: Required. Your API authentication key.
+
+### Body Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `audio_urls` | Array | Yes | An array of objects, each containing an `audio_url` property pointing to an audio file to be concatenated. Must contain at least one item. |
+| `webhook_url` | String | No | A URL to receive a callback notification when processing is complete. If provided, the request will be processed asynchronously. |
+| `id` | String | No | A custom identifier for tracking the request. |
+
+Each object in the `audio_urls` array must have:
+- `audio_url`: String (URI format). The URL of an audio file to be concatenated.
+
+### Example Request
+
+```json
+{
+  "audio_urls": [
+    { "audio_url": "https://example.com/audio1.mp3" },
+    { "audio_url": "https://example.com/audio2.mp3" },
+    { "audio_url": "https://example.com/audio3.mp3" }
+  ],
+  "webhook_url": "https://your-webhook-endpoint.com/callback",
+  "id": "custom-request-id-123"
+}
+```
+
+### Example cURL Command
+
+```bash
+curl -X POST \
+  https://api.example.com/v1/audio/concatenate \
+  -H 'Content-Type: application/json' \
+  -H 'x-api-key: your-api-key-here' \
+  -d '{
+    "audio_urls": [
+      { "audio_url": "https://example.com/audio1.mp3" },
+      { "audio_url": "https://example.com/audio2.mp3" }
+    ],
+    "webhook_url": "https://your-webhook-endpoint.com/callback",
+    "id": "custom-request-id-123"
+  }'
+```
+
+## Response
+
+### Synchronous Response (No webhook_url provided)
+
+If no `webhook_url` is provided, the request will be processed synchronously and return:
+
+```json
+{
+  "code": 200,
+  "id": "custom-request-id-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "response": "https://storage.example.com/combined-audio-file.mp3",
+  "message": "success",
+  "run_time": 2.345,
+  "queue_time": 0,
+  "total_time": 2.345,
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 0,
+  "build_number": "1.0.123"
+}
+```
+
+### Asynchronous Response (webhook_url provided)
+
+If a `webhook_url` is provided, the request will be queued for processing and immediately return:
+
+```json
+{
+  "code": 202,
+  "id": "custom-request-id-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "processing",
+  "pid": 12345,
+  "queue_id": 67890,
+  "max_queue_length": "unlimited",
+  "queue_length": 1,
+  "build_number": "1.0.123"
+}
+```
+
+When processing is complete, a webhook will be sent to the provided URL with the following payload:
+
+```json
+{
+  "endpoint": "/v1/audio/concatenate",
+  "code": 200,
+  "id": "custom-request-id-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "response": "https://storage.example.com/combined-audio-file.mp3",
+  "message": "success",
+  "pid": 12345,
+  "queue_id": 67890,
+  "run_time": 3.456,
+  "queue_time": 1.234,
+  "total_time": 4.690,
+  "queue_length": 0,
+  "build_number": "1.0.123"
+}
+```
+
+### Error Responses
+
+#### Invalid Request Format (400 Bad Request)
+
+```json
+{
+  "code": 400,
+  "id": null,
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "Invalid request: 'audio_urls' is a required property",
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 0,
+  "build_number": "1.0.123"
+}
+```
+
+#### Authentication Error (401 Unauthorized)
+
+```json
+{
+  "code": 401,
+  "message": "Invalid or missing API key",
+  "build_number": "1.0.123"
+}
+```
+
+#### Queue Limit Reached (429 Too Many Requests)
+
+```json
+{
+  "code": 429,
+  "id": "custom-request-id-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "MAX_QUEUE_LENGTH (100) reached",
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 100,
+  "build_number": "1.0.123"
+}
+```
+
+#### Processing Error (500 Internal Server Error)
+
+```json
+{
+  "code": 500,
+  "id": "custom-request-id-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "Error downloading audio file: Connection refused",
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 0,
+  "build_number": "1.0.123"
+}
+```
+
+## Error Handling
+
+- **Missing Required Parameters**: If `audio_urls` is missing or empty, a 400 Bad Request response will be returned.
+- **Invalid URL Format**: If any `audio_url` is not a valid URI, a 400 Bad Request response will be returned.
+- **Authentication Failure**: If the API key is invalid or missing, a 401 Unauthorized response will be returned.
+- **Queue Limit**: If the queue is full (when MAX_QUEUE_LENGTH is set), a 429 Too Many Requests response will be returned.
+- **Processing Errors**: Any errors during audio download, processing, or upload will result in a 500 Internal Server Error response with details in the message field.
+
+## Usage Notes
+
+1. **Asynchronous Processing**: For long audio files, it's recommended to use the `webhook_url` parameter to process the request asynchronously.
+2. **File Formats**: The service supports common audio formats. The output will be in a standard format (typically MP3).
+3. **File Size**: There may be limits on the size of audio files that can be processed. Very large files might cause timeouts or failures.
+4. **Queue Behavior**: If the system is under heavy load, requests with `webhook_url` will be queued. The MAX_QUEUE_LENGTH environment variable controls the maximum queue size.
+
+## Common Issues
+
+1. **Inaccessible Audio URLs**: Ensure all audio URLs are publicly accessible. Private or authentication-required URLs will cause failures.
+2. **Incompatible Audio Formats**: Some exotic audio formats might not be supported. Stick to common formats like MP3, WAV, or AAC.
+3. **Webhook Failures**: If your webhook endpoint is unavailable when the processing completes, you might not receive the completion notification.
+4. **Timeout Issues**: Very large audio files might cause timeouts during download or processing.
+
+## Best Practices
+
+1. **Use Webhooks for Large Files**: Always use the webhook approach for large audio files or when concatenating many files.
+2. **Include an ID**: Always include a custom `id` parameter to help track your requests, especially in webhook responses.
+3. **Error Handling**: Implement robust error handling in your client application to handle various HTTP status codes.
+4. **Webhook Reliability**: Ensure your webhook endpoint is reliable and can handle retries if necessary.
+5. **File Preparation**: Pre-process your audio files to ensure they have compatible formats, sample rates, and channel configurations for best results.
+6. **Queue Monitoring**: Monitor the `queue_length` in responses to understand system load and adjust your request patterns if needed.

docs/cloud-installation/do.md

@@ -0,0 +1,109 @@
+# Installing on Digital Ocean
+
+This guide walks you through deploying the No-Code Architects Toolkit API on Digital Ocean's App Platform.
+
+## Prerequisites
+
+- A Digital Ocean account ([Sign up here](https://www.digitalocean.com/))
+- Basic familiarity with Digital Ocean App Platform
+- A credit/debit card for billing (you'll only be charged for what you use)
+
+## Step 1: Create a New Project
+
+1. Sign in to your Digital Ocean account
+2. Create a new project or select an existing one
+3. This will organize your resources for the NCA Toolkit
+
+## Step 2: Create a Digital Ocean Space
+
+You'll need to create a Space (Digital Ocean's object storage) for the toolkit to store processed files:
+
+1. Navigate to **Spaces Object Storage** in the Digital Ocean dashboard
+2. Click **Create a Space**
+3. Select a region (e.g., New York)
+4. Give your bucket a name (e.g., `nca-toolkit-bucket`)
+5. Select your project
+6. Click **Create Space**
+
+## Step 3: Generate API Keys for Your Space
+
+1. From your new Space, go to **Settings**
+2. Click **Create Access Key**
+3. Select **Full Access**
+4. Give your key a name (e.g., `nca-toolkit-key`)
+5. Click **Create Access Key**
+6. **IMPORTANT**: Save both the Access Key and Secret Key shown - you will only see them once!
+7. Also copy the Space URL (endpoint) for use in the next step
+
+## Step 4: Deploy the App
+
+1. From your Digital Ocean dashboard, click **Create** and select **App**
+2. Choose **Container Image** as the deployment source
+3. Select **Docker Hub** for the repository
+4. Enter `stephengpope/no-code-architects-toolkit` as the image name
+5. Enter `latest` for the image tag
+6. Click **Next**
+7. If needed, edit the name to remove any extra dashes (Digital Ocean may show an error for long names)
+8. Choose **Web Service** as the service type
+
+## Step 5: Configure Resources
+
+1. Select a plan with adequate resources for your needs:
+   - For testing, a $50/month instance provides good performance
+   - For smaller workloads, you can select a smaller instance
+   - Note: You're only charged for the time the server is running
+2. Set Containers to 1
+3. Close the resource selection dialog
+
+## Step 6: Configure Environment Variables
+
+Add the following environment variables exactly as shown (be careful with underscores vs. dashes and avoid any leading/trailing spaces):
+
+1. `API_KEY`: Your API key (e.g., `test123` for testing - change for production)
+2. `S3_ENDPOINT_URL`: The URL of your Space (copied from Step 3)
+3. `S3_ACCESS_KEY`: The access key from Step 3
+4. `S3_SECRET_KEY`: The secret key from Step 3
+5. `S3_BUCKET_NAME`: The name of your Space bucket (e.g., `nca-toolkit-bucket`)
+6. `S3_REGION`: The region code of your Space (e.g., `NYC3` for New York)
+
+## Step 7: Finalize and Deploy
+
+1. For Deployment Region, select a region close to your location (e.g., San Francisco)
+2. You can use the default app name or choose a custom name
+3. Click **Create Resource**
+4. Wait for the deployment to complete (this may take a few minutes)
+   - You may need to refresh the page to see updates
+
+## Step 8: Test Your Deployment
+
+### Using Postman
+
+1. Sign up for or log in to [Postman](https://www.postman.com/)
+2. Import the [NCA Toolkit Postman Collection](https://bit.ly/49Gkh61)
+3. Fork the collection to your workspace
+4. Create a new environment:
+   - Name it "Digital Ocean" or similar
+   - Add a variable `x-api-key` with the value matching your API_KEY (e.g., `test123`)
+   - Add a variable `base_url` with the value of your app's URL (shown in the Digital Ocean dashboard)
+   - Save the environment
+5. In the collection, navigate to the `toolkit/authenticate` endpoint and click Send
+6. If you receive a success response, your deployment is working correctly
+7. Then test the `toolkit/test` endpoint to verify complete functionality
+
+## Monitoring and Management
+
+- **Overview**: View basic information about your app
+- **Insights**: Monitor CPU and memory usage
+- **Runtime Logs**: View logs of API calls and server activity
+- **Console**: Access the server's command line (rarely needed)
+- **Settings**: Modify your app's configuration
+
+## Next Steps
+
+Now that you have successfully deployed the NCA Toolkit API, you can:
+- Explore all the available endpoints in the Postman collection
+- Integrate the API with your applications
+- Consider securing your API key with a more complex value
+- Scale your resources up or down based on your usage requirements
+
+Remember, Digital Ocean charges based on usage, so you can always delete the app when you're not using it to save costs.

docs/cloud-installation/gcp.md

@@ -0,0 +1,140 @@
+# Installing on the Google Cloud Platform (GCP)
+
+## 🎥 Video Instructions
+
+Watch **[Detailed Video Instructions](https://youtu.be/6bC93sek9v8)** to set up the No-Code Architects Toolkit API.
+
+- Use the **Docker Image** below:
+
+  ```
+  stephengpope/no-code-architects-toolkit:latest
+  ```
+
+### Video Resources
+
+- **[Postman Template](https://bit.ly/49Gkh61)**
+- **[NCA Toolkit API GPT](https://bit.ly/4feDDk4)** 
+
+Or use the guide below walks you through the steps to install the NCA Toolkit API on GCP.
+
+---
+
+## **Prerequisites**
+- A Google Cloud account. [Sign up here](https://cloud.google.com/) if you don't already have one.
+  - New users receive $300 in free credits.
+- Basic knowledge of GCP services such as Cloud Run and Cloud Storage.
+- A terminal or code editor for managing files.
+
+---
+
+## **Step 1: Create a Google Cloud Project**
+1. Log into the [GCP Console](https://console.cloud.google.com/).
+2. Click on the **Project Selector** in the top navigation bar and select **New Project**.
+3. Enter a project name, such as `NCA Toolkit Project`.
+4. Click **Create**.
+
+---
+
+## **Step 2: Enable Required APIs**
+Enable the following APIs:
+- **Cloud Storage API**
+- **Cloud Storage JSON API**
+- **Cloud Run API**
+
+### **How to Enable APIs:**
+1. In the GCP Console, navigate to **APIs & Services** > **Enable APIs and Services**.
+2. Search for each API, click on it, and enable it.
+
+---
+
+## **Step 3: Create a Service Account**
+1. Navigate to **IAM & Admin** > **Service Accounts** in the GCP Console.
+2. Click **+ Create Service Account**.
+   - Enter a name (e.g., `NCA Toolkit Service Account`).
+3. Assign the following roles to the service account:
+   - **Storage Admin**
+   - **Viewer**
+4. Click **Done** to create the service account.
+5. Open the service account details and navigate to the **Keys** tab.
+   - Click **Add Key** > **Create New Key**.
+   - Choose **JSON** format, download the file, and store it securely.
+
+---
+
+## **Step 4: Create a Cloud Storage Bucket**
+1. Navigate to **Storage** > **Buckets** in the GCP Console.
+2. Click **+ Create Bucket**.
+   - Choose a unique bucket name (e.g., `nca-toolkit-bucket`).
+   - Leave default settings, but:
+     - Uncheck **Enforce public access prevention**.
+     - Set **Access Control** to **Uniform**.
+3. Click **Create** to finish.
+4. Go to the bucket permissions, and add **allUsers** as a principal with the role:
+   - **Storage Object Viewer**.
+5. Save changes.
+
+---
+
+## **Step 5: Deploy on Google Cloud Run**
+
+### 1. Navigate to Cloud Run
+- Open the **Cloud Run** service in the **Google Cloud Console**.
+
+### 2. Create a New Service
+- Click **Create Service**.
+- Then **Deploy one revision from Docker Hub using the image below**:
+
+  ```
+  stephengpope/no-code-architects-toolkit:latest
+  ```
+
+### 3. Allow Unauthenticated Invocations
+- Check the box to **allow unauthenticated invocations**.
+
+### 4. Configure Resource Allocation
+- Set **Memory**: `16 GB`.
+- Set **CPU**: `4 CPUs`.
+- Set **CPU Allocation**: **Always Allocated**.
+
+### 5. Adjust Scaling Settings
+- **Minimum Instances**: `0` (to minimize cost during idle times).
+- **Maximum Instances**: `5` (adjustable based on expected load).
+
+### 6. Use Second-Generation Servers
+- Scroll to **Platform Version** and select **Second Generation**.
+- Second-generation servers offer better performance and feature support for advanced use cases.
+
+### 7. Add Environment Variables
+- Add the following environment variables:
+- `API_KEY`: Your API key (e.g., `Test123`).
+- `GCP_BUCKET_NAME`: The name of your Cloud Storage bucket.
+- `GCP_SA_CREDENTIALS`: The JSON key of your service account.
+  - Paste the **entire contents** of the downloaded JSON key file into this field.
+  - Ensure:
+    - Proper JSON formatting.
+    - No leading or trailing spaces.
+
+### 8. Configure Advanced Settings
+- Set the **Container Port**: Default to `8080`.
+- **Request Timeout**: `300 seconds` (to handle long-running requests).
+- Enable **Startup Boost** to improve performance for the first request after a cold start.
+
+### 9. Deploy the Service
+- Verify all settings and click **Create**.
+- The deployment process might take a few minutes. Once completed, a green checkmark should appear in the Cloud Run dashboard.
+
+By following these steps, the NCA Toolkit will be successfully deployed and accessible via Google Cloud Run with second-generation servers for optimal performance.
+
+---
+
+## **Step 6: Test the Deployment**
+
+1. Install **[Postman Template](https://bit.ly/49Gkh61)** on your computer.
+2. Import the API example requests from the NCA Toolkit GitHub repository.
+3. Configure two environment variables in Postman:
+   - `base_url`: Your deployed Cloud Run service URL.
+   - `x-api-key`: The API key you configured in **Step 5**.
+4. Use the example requests to validate that the API is functioning correctly.
+5. Use the **[NCA Toolkit API GPT](https://bit.ly/4feDDk4)** to learn more.
+
+By following these steps, your NCA Toolkit API should be successfully deployed on Google Cloud Platform.

docs/code/execute/execute_python.md

@@ -0,0 +1,174 @@
+# Execute Python Code Endpoint
+
+## 1. Overview
+
+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
+
+**URL Path:** `/v1/code/execute/python`
+**HTTP Method:** `POST`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+The request body must be a JSON object with the following properties:
+
+- `code` (string, required): The Python code to be executed.
+- `timeout` (integer, optional): The maximum execution time in seconds, between 1 and 300. Default is 30 seconds.
+- `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` directive in the routes file enforces the following JSON schema for the request body:
+
+```json
+{
+    "type": "object",
+    "properties": {
+        "code": {"type": "string"},
+        "timeout": {"type": "integer", "minimum": 1, "maximum": 300},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["code"],
+    "additionalProperties": False
+}
+```
+
+### Example Request
+
+**Request Payload:**
+
+```json
+{
+    "code": "print('Hello, World!')",
+    "timeout": 10,
+    "webhook_url": "https://example.com/webhook",
+    "id": "unique-request-id"
+}
+```
+
+**cURL Command:**
+
+```bash
+curl -X POST \
+     -H "x-api-key: YOUR_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{"code": "print('Hello, World!')", "timeout": 10, "webhook_url": "https://example.com/webhook", "id": "unique-request-id"}' \
+     http://your-api-endpoint/v1/code/execute/python
+```
+
+## 4. Response
+
+### Success Response
+
+The success response follows the general response format defined in `app.py`. Here's an example:
+
+```json
+{
+    "endpoint": "/v1/code/execute/python",
+    "code": 200,
+    "id": "unique-request-id",
+    "job_id": "generated-job-id",
+    "response": {
+        "result": null,
+        "stdout": "Hello, World!\n",
+        "stderr": "",
+        "exit_code": 0
+    },
+    "message": "success",
+    "pid": 12345,
+    "queue_id": 1234567890,
+    "run_time": 0.123,
+    "queue_time": 0.0,
+    "total_time": 0.123,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+#### Missing or Invalid Parameters
+
+**Status Code:** 400 Bad Request
+
+```json
+{
+    "error": "Missing or invalid parameters",
+    "stdout": "",
+    "exit_code": 400
+}
+```
+
+#### Execution Error
+
+**Status Code:** 400 Bad Request
+
+```json
+{
+    "error": "Error message from the executed code",
+    "stdout": "Output from the executed code",
+    "exit_code": 400
+}
+```
+
+#### 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 various types of errors, including:
+
+- 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)
+
+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 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
+
+- 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
+
+- 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

@@ -0,0 +1,245 @@
+# FFmpeg Compose API Endpoint
+
+## 1. Overview
+
+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`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+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 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.
+- `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.
+  - `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 webhook.
+- `id` (required, string): A unique identifier for the request.
+
+### Example Request
+
+```json
+{
+  "inputs": [
+    {
+      "file_url": "https://example.com/video1.mp4",
+      "options": [
+        {
+          "option": "-ss",
+          "argument": 10
+        },
+        {
+          "option": "-t",
+          "argument": 20
+        }
+      ]
+    },
+    {
+      "file_url": "https://example.com/video2.mp4"
+    }
+  ],
+  "filters": [
+    {
+      "filter": "hflip"
+    }
+  ],
+  "outputs": [
+    {
+      "options": [
+        {
+          "option": "-c:v",
+          "argument": "libx264"
+        },
+        {
+          "option": "-crf",
+          "argument": 23
+        }
+      ]
+    }
+  ],
+  "global_options": [
+    {
+      "option": "-y"
+    }
+  ],
+  "metadata": {
+    "thumbnail": true,
+    "filesize": true,
+    "duration": true,
+    "bitrate": true,
+    "encoder": true
+  },
+  "webhook_url": "https://example.com/webhook",
+  "id": "unique-request-id"
+}
+```
+
+```bash
+curl -X POST \
+  https://api.example.com/v1/ffmpeg/compose \
+  -H 'x-api-key: YOUR_API_KEY' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "inputs": [
+      {
+        "file_url": "https://example.com/video1.mp4",
+        "options": [
+          {
+            "option": "-ss",
+            "argument": 10
+          },
+          {
+            "option": "-t",
+            "argument": 20
+          }
+        ]
+      },
+      {
+        "file_url": "https://example.com/video2.mp4"
+      }
+    ],
+    "filters": [
+      {
+        "filter": "hflip"
+      }
+    ],
+    "outputs": [
+      {
+        "options": [
+          {
+            "option": "-c:v",
+            "argument": "libx264"
+          },
+          {
+            "option": "-crf",
+            "argument": 23
+          }
+        ]
+      }
+    ],
+    "global_options": [
+      {
+        "option": "-y"
+      }
+    ],
+    "metadata": {
+      "thumbnail": true,
+      "filesize": true,
+      "duration": true,
+      "bitrate": true,
+      "encoder": true
+    },
+    "webhook_url": "https://example.com/webhook",
+    "id": "unique-request-id"
+  }'
+```
+
+## 4. Response
+
+### Success Response
+
+The response will be sent to the specified `webhook_url` as a JSON object with the following properties:
+
+- `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 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): 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).
+- `queue_length` (number): The current length of the processing queue.
+- `build_number` (string): The build number of the application.
+
+### Error Responses
+
+- **400 Bad Request**: The request payload is invalid or missing required parameters.
+- **401 Unauthorized**: The provided API key is invalid or missing.
+- **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:
+
+```json
+{
+  "code": 400,
+  "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"
+}
+```
+
+## 5. Error Handling
+
+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.
+
+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 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.
+- 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 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.

docs/image/convert/image_to_video.md

@@ -0,0 +1,159 @@
+# Image to Video Conversion
+
+## 1. Overview
+
+The `/v1/image/convert/video` endpoint is part of the Flask API application and is responsible for converting an image into a video file. This endpoint is registered in the `app.py` file under the `v1_image_convert_video_bp` blueprint, which is imported from the `routes.v1.image.convert.image_to_video` module.
+
+## 2. Endpoint
+
+**URL Path:** `/v1/image/convert/video`
+**HTTP Method:** `POST`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+The request body must be in JSON format and should include the following parameters:
+
+| Parameter   | Type   | Required | Description                                                  |
+|-------------|--------|----------|--------------------------------------------------------------|
+| `image_url` | string | Yes      | The URL of the image to be converted into a video.          |
+| `length`    | number | No       | The desired length of the video in seconds (default: 5).    |
+| `frame_rate`| integer| No       | The frame rate of the output video (default: 30).           |
+| `zoom_speed`| number | No       | The speed of the zoom effect (0-100, default: 3).           |
+| `webhook_url`| string| No       | The URL to receive a webhook notification upon completion.  |
+| `id`        | string | No       | An optional identifier for the request.                      |
+
+The `validate_payload` decorator in the `routes.v1.image.convert.image_to_video` module enforces the following JSON schema for the request body:
+
+```json
+{
+    "type": "object",
+    "properties": {
+        "image_url": {"type": "string", "format": "uri"},
+        "length": {"type": "number", "minimum": 1, "maximum": 60},
+        "frame_rate": {"type": "integer", "minimum": 15, "maximum": 60},
+        "zoom_speed": {"type": "number", "minimum": 0, "maximum": 100},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["image_url"],
+    "additionalProperties": false
+}
+```
+
+### Example Request
+
+```json
+{
+    "image_url": "https://example.com/image.jpg",
+    "length": 10,
+    "frame_rate": 24,
+    "zoom_speed": 5,
+    "webhook_url": "https://example.com/webhook",
+    "id": "request-123"
+}
+```
+
+```bash
+curl -X POST \
+     -H "x-api-key: YOUR_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{"image_url": "https://example.com/image.jpg", "length": 10, "frame_rate": 24, "zoom_speed": 5, "webhook_url": "https://example.com/webhook", "id": "request-123"}' \
+     http://your-api-endpoint/v1/image/convert/video
+```
+
+## 4. Response
+
+### Success Response
+
+Upon successful processing, the endpoint returns a JSON response with the following structure:
+
+```json
+{
+    "code": 200,
+    "id": "request-123",
+    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+    "response": "https://cloud-storage.example.com/converted-video.mp4",
+    "message": "success",
+    "run_time": 2.345,
+    "queue_time": 0.123,
+    "total_time": 2.468,
+    "pid": 12345,
+    "queue_id": 1234567890,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+The `response` field contains the URL of the converted video file uploaded to cloud storage.
+
+### Error Responses
+
+#### 429 Too Many Requests
+
+If the maximum queue length is reached, the endpoint returns a 429 Too Many Requests response:
+
+```json
+{
+    "code": 429,
+    "id": "request-123",
+    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+    "message": "MAX_QUEUE_LENGTH (10) reached",
+    "pid": 12345,
+    "queue_id": 1234567890,
+    "queue_length": 10,
+    "build_number": "1.0.0"
+}
+```
+
+#### 500 Internal Server Error
+
+If an exception occurs during the image-to-video conversion process, the endpoint returns a 500 Internal Server Error response:
+
+```json
+{
+    "code": 500,
+    "id": "request-123",
+    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+    "message": "Error message describing the exception",
+    "pid": 12345,
+    "queue_id": 1234567890,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+## 5. Error Handling
+
+The endpoint handles the following types of errors:
+
+- **Missing or invalid parameters**: If the request body is missing required parameters or contains invalid parameter values, the `validate_payload` decorator will return a 400 Bad Request response with a descriptive error message.
+- **Queue length exceeded**: If the maximum queue length is reached and the `bypass_queue` parameter is set to `False`, the endpoint returns a 429 Too Many Requests response.
+- **Exceptions during processing**: If an exception occurs during the image-to-video conversion process, the endpoint returns a 500 Internal Server Error response with the error message.
+
+## 6. Usage Notes
+
+- The `image_url` parameter must be a valid URL pointing to an image file.
+- The `length` parameter specifies the duration of the output video in seconds and must be between 1 and 60.
+- The `frame_rate` parameter specifies the frame rate of the output video and must be between 15 and 60.
+- The `zoom_speed` parameter controls the speed of the zoom effect and must be between 0 and 100.
+- The `webhook_url` parameter is optional and can be used to receive a notification when the conversion is complete.
+- The `id` parameter is optional and can be used to identify the request.
+
+## 7. Common Issues
+
+- Providing an invalid or inaccessible `image_url` will result in an error during processing.
+- Specifying invalid parameter values outside the allowed ranges will result in a 400 Bad Request response.
+- If the maximum queue length is reached and the `bypass_queue` parameter is set to `False`, the request will be rejected with a 429 Too Many Requests response.
+
+## 8. Best Practices
+
+- Validate the `image_url` parameter before sending the request to ensure it points to a valid and accessible image file.
+- Use the `webhook_url` parameter to receive notifications about the completion of the conversion process, rather than polling the API repeatedly.
+- Provide the `id` parameter to easily identify and track the request in logs or notifications.
+- Consider setting the `bypass_queue` parameter to `True` for time-sensitive requests to bypass the queue and process the request immediately.

docs/image/screenshot_webpage.md

@@ -0,0 +1,218 @@
+# Playwright Screenshot Endpoint
+
+**Implemented by:** [Harrison Fisher](https://github.com/HarrisonFisher)
+
+## ⚠️ Disclaimer
+- This endpoint is **not intended to bypass CAPTCHAs, Cloudflare**, or other anti-bot protections.
+- Please **do not create issues or requests** asking for CAPTCHA or Cloudflare bypass features.
+- It will not work for sites with such defenses, and attempting to automate against protected sites could result in your IP address being blacklisted by Cloudflare or similar services.
+- The screenshot endpoint supports custom HTML, JavaScript, and CSS input for flexible rendering and automation, as an alternative to using a URL.
+- This feature should only be used on sites you own or have explicit permission to automate.
+
+
+## 1. Overview
+
+The `/v1/image/screenshot/webpage` endpoint allows you to capture screenshots of web pages using the Playwright browser automation library. It supports advanced options such as viewport size, device emulation, cookies, headers, element targeting, and more. Screenshots are uploaded to cloud storage, and the resulting URL is returned. This endpoint is part of the v1 API suite and is registered in the main Flask application as a blueprint.
+
+## 2. Endpoint
+
+- **URL Path:** `/v1/image/screenshot/webpage`
+- **HTTP Method:** `POST`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): Your API key for authentication.
+- `Content-Type`: `application/json`
+
+### Body Parameters
+
+The request body must be a JSON object with the following properties:
+
+- `url` (string, required): The URL of the web page to capture.
+- `html` (string, optional): Raw HTML content to render and capture.  
+  **Note:** Either `url` or `html` must be provided, but not both.
+- `viewport_width` (integer, optional): Viewport width in pixels.
+- `viewport_height` (integer, optional): Viewport height in pixels.
+- `full_page` (boolean, optional): Capture the full scrollable page. Default: `false`.
+- `format` (string, optional): Image format, either `png` or `jpeg`. Default: `png`.
+- `delay` (integer, optional): Delay in milliseconds before taking the screenshot.
+- `device_scale_factor` (number, optional): Device scale factor (e.g., 2 for retina).
+- `user_agent` (string, optional): Custom user agent string.
+- `cookies` (array, optional): List of cookies to set. Each cookie is an object with `name`, `value`, and `domain`.
+- `headers` (object, optional): Additional HTTP headers to set.
+- `quality` (integer, optional): JPEG quality (0-100, only for `jpeg` format).
+- `clip` (object, optional): Region to capture, with `x`, `y`, `width`, `height` (all numbers).
+- `timeout` (integer, optional): Navigation timeout in milliseconds. Minimum: 100.
+- `wait_until` (string, optional): When to consider navigation succeeded. One of `load`, `domcontentloaded`, `networkidle`, `networkidle2`. Default: `load`.
+- `wait_for_selector` (string, optional): Wait for a selector before screenshot.
+- `emulate` (object, optional): Emulation options, e.g., `{ "color_scheme": "dark" }`.
+- `omit_background` (boolean, optional): Hide default white background. Default: `false`.
+- `selector` (string, optional): CSS selector for a specific element to screenshot.
+- `webhook_url` (string, optional): If provided, results are sent to this URL asynchronously.
+- `id` (string, optional): Custom identifier for the request.
+- `js` (string, optional): JavaScript code to inject into the page before taking the screenshot.
+- `css` (string, optional): CSS code to inject into the page before taking the screenshot.
+
+#### Example Request
+
+```json
+{
+    "url": "https://example.com",
+    "viewport_width": 1280,
+    "viewport_height": 720,
+    "js": "document.body.style.background = 'red';",
+    "css": "body { font-size: 30px; }",
+    "full_page": true,
+    "format": "png",
+    "delay": 500,
+    "device_scale_factor": 2,
+    "user_agent": "CustomAgent/1.0",
+    "cookies": [
+        {
+            "name": "test_cookie",
+            "value": "test_value",
+            "domain": "example.com",
+            "path": "/"
+        }
+    ],
+    "headers": {
+        "Accept-Language": "en-US,en;q=0.9"
+    },
+    "quality": 90,
+    "clip": {
+        "x": 0,
+        "y": 0,
+        "width": 800,
+        "height": 600
+    },
+    "timeout": 10000,
+    "wait_until": "networkidle",
+    "wait_for_selector": "#main-content",
+    "selector": "#main-content",
+    "emulate": {
+        "color_scheme": "dark"
+    },
+    "omit_background": true,
+    "webhook_url": "https://your-webhook.com/callback",
+    "id": "custom-job-123"
+}
+```
+
+**cURL Example:**
+
+```bash
+curl -X POST \
+  -H "x-api-key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://example.com",
+    "viewport_width": 1280,
+    "viewport_height": 720,
+    "js": "document.body.style.background = '\''red'\'';",
+    "css": "body { font-size: 30px; }",
+    "full_page": true,
+    "format": "png",
+    "delay": 500,
+    "device_scale_factor": 2,
+    "user_agent": "CustomAgent/1.0",
+    "cookies": [
+      {"name": "test_cookie", "value": "test_value", "domain": "example.com", "path": "/"}
+    ],
+    "headers": {"Accept-Language": "en-US,en;q=0.9"},
+    "quality": 90,
+    "clip": {"x": 0, "y": 0, "width": 800, "height": 600},
+    "timeout": 10000,
+    "wait_until": "networkidle",
+    "wait_for_selector": "#main-content",
+    "selector": "#main-content",
+    "emulate": {"color_scheme": "dark"},
+    "omit_background": true,
+    "webhook_url": "https://your-webhook.com/callback",
+    "id": "custom-job-123"
+  }' \
+  https://your-api-endpoint.com/v1/image/screenshot/webpage
+```
+
+## 4. Response
+
+### Success Response
+
+The response is a JSON object containing the cloud storage URL of the screenshot and job metadata. If a `webhook_url` is provided, the result is sent asynchronously to the webhook.
+
+```json
+{
+  "endpoint": "/v1/image/screenshot/webpage",
+  "code": 200,
+  "id": "custom-job-123",
+  "job_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
+  "response": "https://cloud.example.com/screenshot.png",
+  "message": "success",
+  "pid": 12345,
+  "queue_id": 140682639937472,
+  "run_time": 2.345,
+  "queue_time": 0.012,
+  "total_time": 2.357,
+  "queue_length": 0,
+  "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+- **400 Bad Request**: Invalid or missing parameters.
+- **401 Unauthorized**: Invalid or missing API key.
+- **429 Too Many Requests**: Queue is full.
+- **500 Internal Server Error**: An error occurred during processing.
+
+Example error response:
+
+```json
+{
+  "endpoint": "/v1/image/screenshot/webpage",
+  "code": 500,
+  "id": "custom-job-123",
+  "job_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
+  "response": null,
+  "message": "Error message details",
+  "pid": 12345,
+  "queue_id": 140682639937472,
+  "run_time": 0.123,
+  "queue_time": 0.056,
+  "total_time": 0.179,
+  "queue_length": 1,
+  "build_number": "1.0.0"
+}
+```
+
+## 5. Error Handling
+
+- **Missing or invalid parameters**: Returns 400 with details.
+- **Authentication failure**: Returns 401.
+- **Queue full**: Returns 429.
+- **Processing error**: Returns 500 with error message.
+
+## 6. Usage Notes
+
+- If `webhook_url` is provided, the request is processed asynchronously and the result is sent to the webhook.
+- Screenshots are always uploaded to cloud storage; the response contains the file URL.
+- Use `selector` to capture a specific element instead of the full page.
+- The `clip` parameter allows capturing a specific region.
+- The endpoint enforces strict payload validation.
+
+## 7. Common Issues
+
+- Invalid or inaccessible URL.
+- Selector not found (if using `wait_for_selector` or `selector`).
+- Cookie domain mismatch.
+- Timeout errors for slow-loading pages.
+- Invalid API key.
+
+## 8. Best Practices
+
+- Always validate your input parameters before sending the request.
+- Use unique `id` values for tracking jobs.
+- Monitor queue length and handle 429 errors gracefully.
+- Use HTTPS for all URLs and webhooks.
+- Test your selectors and page state locally before automating screenshots.

docs/media/convert/media_convert.md

@@ -0,0 +1,138 @@
+# Media Convert Endpoint Documentation
+
+## 1. Overview
+
+The `/v1/media/convert` endpoint is part of the Flask API application and is responsible for converting media files (audio or video) from one format to another. This endpoint fits into the overall API structure as a part of the `v1` blueprint, which contains various media-related functionalities.
+
+## 2. Endpoint
+
+**URL Path:** `/v1/media/convert`
+**HTTP Method:** `POST`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+The request body must be a JSON object with the following properties:
+
+- `media_url` (required, string): The URL of the media file to be converted.
+- `format` (required, string): The desired output format for the converted media file.
+- `video_codec` (optional, string): The video codec to be used for the conversion. Default is `libx264`.
+- `video_preset` (optional, string): The video preset to be used for the conversion. Default is `medium`.
+- `video_crf` (optional, number): The Constant Rate Factor (CRF) value for video encoding. Must be between 0 and 51. Default is 23.
+- `audio_codec` (optional, string): The audio codec to be used for the conversion. Default is `aac`.
+- `audio_bitrate` (optional, string): The audio bitrate to be used for the conversion. Default is `128k`.
+- `webhook_url` (optional, string): The URL to receive a webhook notification upon completion of the conversion process.
+- `id` (optional, string): An optional identifier for the conversion request.
+
+### Example Request
+
+```json
+{
+  "media_url": "https://example.com/video.mp4",
+  "format": "avi",
+  "video_codec": "libx264",
+  "video_preset": "medium",
+  "video_crf": 23,
+  "audio_codec": "aac",
+  "audio_bitrate": "128k",
+  "webhook_url": "https://example.com/webhook",
+  "id": "unique-request-id"
+}
+```
+
+```bash
+curl -X POST \
+  https://api.example.com/v1/media/convert \
+  -H 'x-api-key: YOUR_API_KEY' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "media_url": "https://example.com/video.mp4",
+    "format": "avi",
+    "video_codec": "libx264",
+    "video_preset": "medium",
+    "video_crf": 23,
+    "audio_codec": "aac",
+    "audio_bitrate": "128k",
+    "webhook_url": "https://example.com/webhook",
+    "id": "unique-request-id"
+  }'
+```
+
+## 4. Response
+
+### Success Response
+
+The success response will be a JSON object containing the URL of the converted media file uploaded to cloud storage, the endpoint path, and a status code of 200.
+
+```json
+{
+  "code": 200,
+  "id": "unique-request-id",
+  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+  "response": "https://cloud.example.com/converted-video.avi",
+  "message": "success",
+  "pid": 12345,
+  "queue_id": 1234567890,
+  "run_time": 10.234,
+  "queue_time": 0.123,
+  "total_time": 10.357,
+  "queue_length": 0,
+  "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+- **400 Bad Request**: Returned when the request payload is missing or invalid.
+- **401 Unauthorized**: Returned when the `x-api-key` header is missing or invalid.
+- **500 Internal Server Error**: Returned when an unexpected error occurs during the conversion process.
+
+Example error response:
+
+```json
+{
+  "code": 400,
+  "id": "unique-request-id",
+  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+  "message": "Invalid request payload",
+  "pid": 12345,
+  "queue_id": 1234567890,
+  "queue_length": 0,
+  "build_number": "1.0.0"
+}
+```
+
+## 5. Error Handling
+
+The endpoint uses the `validate_payload` decorator to validate the request payload against a JSON schema. If the payload is missing or invalid, a 400 Bad Request error is returned.
+
+The `authenticate` decorator is used to ensure that the request includes a valid `x-api-key` header. If the header is missing or invalid, a 401 Unauthorized error is returned.
+
+If an unexpected error occurs during the conversion process, a 500 Internal Server Error is returned, and the error is logged.
+
+## 6. Usage Notes
+
+- The `media_url` parameter must be a valid URL pointing to the media file to be converted.
+- The `format` parameter must be a valid media format supported by the conversion process.
+- The optional parameters (`video_codec`, `video_preset`, `video_crf`, `audio_codec`, `audio_bitrate`) allow you to customize the conversion settings.
+- If the `webhook_url` parameter is provided, a webhook notification will be sent to the specified URL upon completion of the conversion process.
+- The `id` parameter is optional and can be used to identify the conversion request.
+
+## 7. Common Issues
+
+- Providing an invalid or inaccessible `media_url`.
+- Specifying an unsupported `format`.
+- Providing invalid values for the optional parameters (e.g., `video_crf` outside the valid range).
+
+## 8. Best Practices
+
+- Always validate the input parameters on the client-side before sending the request.
+- Use the `id` parameter to track and identify conversion requests.
+- Provide a `webhook_url` to receive notifications about the conversion process completion.
+- Monitor the API logs for any errors or issues during the conversion process.
+- Consider implementing rate limiting or queue management to handle high volumes of requests.

docs/media/convert/media_to_mp3.md

@@ -0,0 +1,142 @@
+# Media to MP3 Conversion
+
+The `/v1/media/convert/mp3` endpoint is part of the Flask API application and is responsible for converting various media files into MP3 format. This endpoint is registered in the `app.py` file under the `v1_media_convert_mp3_bp` blueprint.
+
+## Endpoint Details
+
+**URL Path:** `/v1/media/convert/mp3`
+
+## 1. Overview
+
+The `/v1/media/convert/mp3` endpoint is a part of the API's media transformation functionality. It allows users to convert various media files (audio or video) to MP3 format. This endpoint fits into the overall API structure as a part of the `v1` namespace, which represents the first version of the API.
+
+## 2. Endpoint
+
+```
+POST /v1/media/convert/mp3
+```
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+- `media_url` (required, string): The URL of the media file to be converted.
+- `webhook_url` (optional, string): The URL to receive a webhook notification upon completion.
+- `id` (optional, string): A unique identifier for the request.
+- `bitrate` (optional, string): The desired bitrate for the output MP3 file, in the format `<value>k` (e.g., `128k`). If not provided, defaults to `128k`.
+
+The `validate_payload` directive in the routes file enforces the following JSON schema for the request body:
+
+```json
+{
+    "type": "object",
+    "properties": {
+        "media_url": {"type": "string", "format": "uri"},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"},
+        "bitrate": {"type": "string", "pattern": "^[0-9]+k$"}
+    },
+    "required": ["media_url"],
+    "additionalProperties": False
+}
+```
+
+### Example Request
+
+```json
+{
+    "media_url": "https://example.com/video.mp4",
+    "webhook_url": "https://example.com/webhook",
+    "id": "unique-request-id",
+    "bitrate": "192k"
+}
+```
+
+```bash
+curl -X POST \
+     -H "x-api-key: YOUR_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{"media_url": "https://example.com/video.mp4", "webhook_url": "https://example.com/webhook", "id": "unique-request-id", "bitrate": "192k"}' \
+     https://your-api-endpoint.com/v1/media/convert/mp3
+```
+
+## 4. Response
+
+### Success Response
+
+The success response follows the general response structure defined in `app.py`. Here's an example:
+
+```json
+{
+    "endpoint": "/v1/media/convert/mp3",
+    "code": 200,
+    "id": "unique-request-id",
+    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+    "response": "https://cloud-storage.example.com/converted-file.mp3",
+    "message": "success",
+    "pid": 12345,
+    "queue_id": 6789,
+    "run_time": 5.234,
+    "queue_time": 0.123,
+    "total_time": 5.357,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+- **400 Bad Request**: Returned when the request payload is invalid or missing required parameters.
+- **401 Unauthorized**: Returned when the `x-api-key` header is missing or invalid.
+- **500 Internal Server Error**: Returned when an unexpected error occurs during the conversion process.
+
+Example error response:
+
+```json
+{
+    "code": 400,
+    "id": "unique-request-id",
+    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+    "message": "Invalid request payload: 'media_url' is a required property",
+    "pid": 12345,
+    "queue_id": 6789,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+## 5. Error Handling
+
+The endpoint handles the following common errors:
+
+- Missing or invalid `media_url` parameter: Returns a 400 Bad Request error.
+- Invalid `bitrate` parameter: Returns a 400 Bad Request error.
+- Authentication failure: Returns a 401 Unauthorized error.
+- Unexpected exceptions during the conversion process: Returns a 500 Internal Server Error.
+
+Additionally, the main application context (`app.py`) includes error handling for queue overload. If the maximum queue length is reached, the endpoint will return a 429 Too Many Requests error.
+
+## 6. Usage Notes
+
+- The `media_url` parameter should point to a valid media file (audio or video) that can be converted to MP3 format.
+- If the `webhook_url` parameter is provided, a webhook notification will be sent to the specified URL upon completion of the conversion process.
+- The `id` parameter can be used to uniquely identify the request, which can be helpful for tracking and logging purposes.
+- The `bitrate` parameter allows you to specify the desired bitrate for the output MP3 file. If not provided, the default bitrate of 128k will be used.
+
+## 7. Common Issues
+
+- Providing an invalid or inaccessible `media_url`.
+- Attempting to convert unsupported media formats.
+- Exceeding the maximum queue length, resulting in a 429 Too Many Requests error.
+
+## 8. Best Practices
+
+- Validate the `media_url` parameter before sending the request to ensure it points to a valid and accessible media file.
+- Consider providing a `webhook_url` parameter to receive notifications about the conversion process completion.
+- Use a unique `id` parameter for each request to facilitate tracking and logging.
+- Implement retry mechanisms in case of transient errors or queue overload situations.
+- Monitor the API logs for any errors or issues during the conversion process.

docs/media/cut.md

@@ -0,0 +1,169 @@
+# Media Cut Endpoint
+
+## 1. Overview
+
+The `/v1/media/cut` endpoint is part of the Flask API application and is designed to cut specified segments from a media file (video or audio) with optional encoding settings. This endpoint fits into the overall API structure as a part of the `v1` blueprint, which contains various media-related functionalities.
+
+## 2. Endpoint
+
+**URL Path:** `/v1/media/cut`
+**HTTP Method:** `POST`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+The request body must be a JSON object with the following properties:
+
+- `media_url` (required, string): The URL of the media file to be cut.
+- `cuts` (required, array of objects): An array of cut segments, where each object has the following properties:
+  - `start` (required, string): The start time of the cut segment in the format `hh:mm:ss.ms`.
+  - `end` (required, string): The end time of the cut segment in the format `hh:mm:ss.ms`.
+- `video_codec` (optional, string): The video codec to be used for encoding the output file. Default is `libx264`.
+- `video_preset` (optional, string): The video preset to be used for encoding the output file. Default is `medium`.
+- `video_crf` (optional, number): The Constant Rate Factor (CRF) value for video encoding. Must be between 0 and 51. Default is 23.
+- `audio_codec` (optional, string): The audio codec to be used for encoding the output file. Default is `aac`.
+- `audio_bitrate` (optional, string): The audio bitrate to be used for encoding the output file. Default is `128k`.
+- `webhook_url` (optional, string): The URL to receive a webhook notification upon completion of the task.
+- `id` (optional, string): A unique identifier for the request.
+
+### Example Request
+
+```json
+{
+  "media_url": "https://example.com/video.mp4",
+  "cuts": [
+    {
+      "start": "00:00:10.000",
+      "end": "00:00:20.000"
+    },
+    {
+      "start": "00:00:30.000",
+      "end": "00:00:40.000"
+    }
+  ],
+  "video_codec": "libx264",
+  "video_preset": "medium",
+  "video_crf": 23,
+  "audio_codec": "aac",
+  "audio_bitrate": "128k",
+  "webhook_url": "https://example.com/webhook",
+  "id": "unique-request-id"
+}
+```
+
+```
+curl -X POST \
+  https://api.example.com/v1/media/cut \
+  -H 'x-api-key: YOUR_API_KEY' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "media_url": "https://example.com/video.mp4",
+    "cuts": [
+      {
+        "start": "00:00:10.000",
+        "end": "00:00:20.000"
+      },
+      {
+        "start": "00:00:30.000",
+        "end": "00:00:40.000"
+      }
+    ],
+    "video_codec": "libx264",
+    "video_preset": "medium",
+    "video_crf": 23,
+    "audio_codec": "aac",
+    "audio_bitrate": "128k",
+    "webhook_url": "https://example.com/webhook",
+    "id": "unique-request-id"
+  }'
+```
+
+## 4. Response
+
+### Success Response
+
+The success response follows the general response structure defined in the `app.py` file. Here's an example:
+
+```json
+{
+  "code": 200,
+  "id": "unique-request-id",
+  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+  "response": {
+    "file_url": "https://example.com/output.mp4"
+  },
+  "message": "success",
+  "run_time": 5.234,
+  "queue_time": 0.012,
+  "total_time": 5.246,
+  "pid": 12345,
+  "queue_id": 1234567890,
+  "queue_length": 0,
+  "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+- **400 Bad Request**: Returned when the request payload is missing or invalid.
+
+  ```json
+  {
+    "code": 400,
+    "message": "Invalid request payload"
+  }
+  ```
+
+- **401 Unauthorized**: Returned when the `x-api-key` header is missing or invalid.
+
+  ```json
+  {
+    "code": 401,
+    "message": "Unauthorized"
+  }
+  ```
+
+- **500 Internal Server Error**: Returned when an unexpected error occurs on the server.
+
+  ```json
+  {
+    "code": 500,
+    "message": "Internal Server Error"
+  }
+  ```
+
+## 5. Error Handling
+
+The endpoint handles the following common errors:
+
+- Missing or invalid request parameters: Returns a 400 Bad Request error.
+- Authentication failure: Returns a 401 Unauthorized error if the `x-api-key` header is missing or invalid.
+- Unexpected exceptions: Returns a 500 Internal Server Error if an unexpected exception occurs during the media cut process.
+
+The main application context (`app.py`) also includes error handling for queue overload. If the maximum queue length is reached, the endpoint returns a 429 Too Many Requests error.
+
+## 6. Usage Notes
+
+- The `media_url` parameter must be a valid URL pointing to a media file (video or audio).
+- The `cuts` parameter must be an array of objects, where each object specifies a start and end time for a cut segment in the format `hh:mm:ss.ms`.
+- The optional encoding parameters (`video_codec`, `video_preset`, `video_crf`, `audio_codec`, `audio_bitrate`) can be used to customize the output file encoding settings.
+- The `webhook_url` parameter is optional and can be used to receive a webhook notification upon completion of the task.
+- The `id` parameter is optional and can be used to uniquely identify the request.
+
+## 7. Common Issues
+
+- Providing an invalid or inaccessible `media_url`.
+- Providing invalid or out-of-range values for the encoding parameters.
+- Providing overlapping or invalid cut segments in the `cuts` parameter.
+
+## 8. Best Practices
+
+- Validate the input parameters on the client-side before sending the request.
+- Use the `webhook_url` parameter to receive notifications and handle the response asynchronously.
+- Monitor the `queue_length` parameter in the response to manage the load on the API.
+- Use the `id` parameter to correlate requests and responses for better tracking and debugging.

docs/media/download.md

@@ -0,0 +1,317 @@
+# Media Download API Endpoint Documentation
+
+## Overview
+
+The `/v1/BETA/media/download` endpoint provides a powerful interface for downloading media content from various online sources using the yt-dlp library. This endpoint is part of the v1 media services in the API structure, allowing users to download videos, extract audio, and retrieve thumbnails and subtitles from supported platforms. The endpoint handles authentication, request validation, and queues tasks for processing, making it suitable for handling resource-intensive media downloads without blocking the main application thread.
+
+## Endpoint
+
+- **URL**: `/v1/BETA/media/download`
+- **Method**: `POST`
+- **Blueprint**: `v1_media_download_bp`
+
+## Request
+
+### Headers
+
+- `x-api-key`: Required for authentication (handled by the `@authenticate` decorator)
+
+### Body Parameters
+
+#### Required Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `media_url` | string (URI format) | The URL of the media to download |
+
+#### Optional Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `webhook_url` | string (URI format) | URL to receive the result when processing is complete |
+| `id` | string | Custom identifier for tracking the request |
+| `cookie` | string | Path to cookie file, URL to cookie file, or cookie string in Netscape format |
+| `cloud_upload` | boolean | When true (default), the downloaded media will be uploaded to cloud storage and a cloud URL will be returned. When false, the direct download URL of the media will be returned instead. |
+
+#### Format Options (Optional)
+
+```json
+"format": {
+  "quality": "string",     // Quality specification (e.g., "best")
+  "format_id": "string",   // Specific format ID
+  "resolution": "string",  // Resolution specification (e.g., "720p")
+  "video_codec": "string", // Video codec preference
+  "audio_codec": "string"  // Audio codec preference
+}
+```
+
+#### Audio Options (Optional)
+
+```json
+"audio": {
+  "extract": boolean,      // Whether to extract audio
+  "format": "string",      // Audio format (e.g., "mp3", "m4a")
+  "quality": "string"      // Audio quality specification
+}
+```
+
+#### Thumbnail Options (Optional)
+
+```json
+"thumbnails": {
+  "download": boolean,     // Whether to download thumbnails
+  "download_all": boolean, // Whether to download all available thumbnails
+  "formats": ["string"],   // Array of thumbnail formats to download
+  "convert": boolean,      // Whether to convert thumbnails
+  "embed_in_audio": boolean // Whether to embed thumbnails in audio files
+}
+```
+
+#### Subtitle Options (Optional)
+
+```json
+"subtitles": {
+  "download": boolean,     // Whether to download subtitles
+  "languages": ["string"], // Array of language codes for subtitles
+  "formats": ["string"]    // Array of subtitle formats to download
+}
+```
+
+#### Download Options (Optional)
+
+```json
+"download": {
+  "max_filesize": integer, // Maximum file size in bytes
+  "rate_limit": "string",  // Download rate limit (e.g., "50K")
+  "retries": integer       // Number of download retry attempts
+}
+```
+
+### Example Request
+
+```json
+{
+  "media_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+  "webhook_url": "https://example.com/webhook",
+  "id": "custom-request-123",
+  "cookie": "# Netscape HTTP Cookie File\n.youtube.com\tTRUE\t/\tFALSE\t0\tCONSENT\tYES+cb",
+  "cloud_upload": true,
+  "format": {
+    "quality": "best",
+    "resolution": "720p"
+  },
+  "audio": {
+    "extract": true,
+    "format": "mp3"
+  },
+  "thumbnails": {
+    "download": true
+  }
+}
+```
+
+### Example cURL Command
+
+```bash
+curl -X POST \
+  https://api.example.com/v1/BETA/media/download \
+  -H 'Content-Type: application/json' \
+  -H 'x-api-key: your-api-key-here' \
+  -d '{
+    "media_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+    "webhook_url": "https://example.com/webhook",
+    "id": "custom-request-123",
+    "cookie": "# Netscape HTTP Cookie File\n.youtube.com\tTRUE\t/\tFALSE\t0\tCONSENT\tYES+cb",
+    "cloud_upload": true,
+    "format": {
+      "quality": "best",
+      "resolution": "720p"
+    },
+    "audio": {
+      "extract": true,
+      "format": "mp3"
+    },
+    "thumbnails": {
+      "download": true
+    }
+  }'
+```
+
+## Response
+
+### Immediate Response (When Using Webhook)
+
+When a webhook URL is provided, the API will queue the task and return an immediate response with a 202 status code:
+
+```json
+{
+  "code": 202,
+  "id": "custom-request-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "processing",
+  "pid": 12345,
+  "queue_id": 67890,
+  "max_queue_length": "unlimited",
+  "queue_length": 3,
+  "build_number": "1.0.123"
+}
+```
+
+### Success Response (When Not Using Webhook or When Webhook Is Called)
+
+```json
+{
+  "code": 200,
+  "id": "custom-request-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "response": {
+    "media": {
+      "media_url": "https://storage.example.com/media/video-123.mp4",
+      "title": "Never Gonna Give You Up",
+      "format_id": "22",
+      "ext": "mp4",
+      "resolution": "720p",
+      "filesize": 12345678,
+      "width": 1280,
+      "height": 720,
+      "fps": 30,
+      "video_codec": "avc1.4d401f",
+      "audio_codec": "mp4a.40.2",
+      "upload_date": "20090325",
+      "duration": 212,
+      "view_count": 1234567890,
+      "uploader": "Rick Astley",
+      "uploader_id": "RickAstleyVEVO",
+      "description": "Official music video for Rick Astley - Never Gonna Give You Up"
+    },
+    "thumbnails": [
+      {
+        "id": "default",
+        "image_url": "https://storage.example.com/media/thumbnail-123.jpg",
+        "width": 1280,
+        "height": 720,
+        "original_format": "jpg",
+        "converted": false
+      }
+    ]
+  },
+  "message": "success",
+  "pid": 12345,
+  "queue_id": 67890,
+  "run_time": 5.123,
+  "queue_time": 0.456,
+  "total_time": 5.579,
+  "queue_length": 2,
+  "build_number": "1.0.123"
+}
+```
+
+### Error Responses
+
+#### Invalid Request (400)
+
+```json
+{
+  "code": 400,
+  "id": "custom-request-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "Invalid request: 'media_url' is a required property",
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 2,
+  "build_number": "1.0.123"
+}
+```
+
+#### Authentication Error (401)
+
+```json
+{
+  "code": 401,
+  "message": "Invalid API key",
+  "build_number": "1.0.123"
+}
+```
+
+#### Queue Full (429)
+
+```json
+{
+  "code": 429,
+  "id": "custom-request-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "MAX_QUEUE_LENGTH (100) reached",
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 100,
+  "build_number": "1.0.123"
+}
+```
+
+#### Server Error (500)
+
+```json
+{
+  "code": 500,
+  "id": "custom-request-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "Error during download process - HTTP Error 403: Forbidden",
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 2,
+  "build_number": "1.0.123"
+}
+```
+
+## Error Handling
+
+The endpoint handles various error scenarios:
+
+- **Missing Required Parameters**: Returns a 400 status code with details about the missing parameter
+- **Invalid Parameter Format**: Returns a 400 status code if parameters don't match the expected format
+- **Authentication Failures**: Returns a 401 status code if the API key is invalid or missing
+- **Queue Limits**: Returns a 429 status code if the task queue is full (when MAX_QUEUE_LENGTH is set)
+- **Download Failures**: Returns a 500 status code with details about the download failure
+- **Media Source Errors**: Returns a 500 status code if the media source is unavailable or restricted
+
+## Usage Notes
+
+1. **Webhook Handling**: 
+   - When providing a `webhook_url`, the request will be queued and processed asynchronously
+   - Without a `webhook_url`, the request will be processed synchronously, which may lead to longer response times
+
+2. **Format Selection**:
+   - The `format` options allow fine-grained control over the downloaded media quality
+   - When multiple format options are specified, they are combined with a '+' separator
+
+3. **Audio Extraction**:
+   - Setting `audio.extract` to `true` will extract audio from the media
+   - Specify `audio.format` to control the output audio format (e.g., "mp3", "m4a")
+
+4. **Thumbnail Handling**:
+   - When `thumbnails.download` is `true`, the API will download and provide URLs for thumbnails
+   - Use `thumbnails.download_all` to retrieve all available thumbnails
+
+5. **Rate Limiting**:
+   - Use `download.rate_limit` to control download speed (e.g., "50K" for 50 KB/s)
+   - This can help prevent IP blocking from some media sources
+
+## Common Issues
+
+1. **Geo-restricted Content**: Some media may be unavailable in certain regions
+2. **Rate Limiting**: Media sources may rate-limit or block frequent downloads
+3. **Large File Downloads**: Very large files may time out during download
+4. **Format Availability**: Not all requested formats may be available for all media sources
+5. **Webhook Failures**: If the webhook URL is unreachable, you won't receive the final result
+6. **Queue Overflow**: Requests may be rejected if the processing queue is full
+
+## Best Practices
+
+1. **Use Webhooks for Large Downloads**: Always use webhooks for potentially large or slow downloads to avoid timeout issues
+2. **Specify Format Constraints**: Be specific about format requirements to avoid unnecessarily large downloads
+3. **Handle Thumbnails Separately**: For efficiency, only request thumbnails when needed
+4. **Implement Retry Logic**: Implement client-side retry logic for handling temporary failures
+5. **Monitor Queue Length**: Check the `queue_length` in responses to gauge system load
+6. **Use Reasonable Rate Limits**: Set appropriate `download.rate_limit` values to avoid being blocked by media sources
+7. **Validate Media URLs**: Ensure media URLs are valid and accessible before submitting
+8. **Store Downloaded Media**: The cloud URLs provided in responses may have expiration times, so download and store important media promptly

docs/media/feedback.md

@@ -0,0 +1,44 @@
+# Media Feedback Portal
+
+This endpoint serves a static web page for collecting media feedback.
+
+## Endpoint
+
+```
+GET /v1/media/feedback
+```
+
+### Authentication
+
+This endpoint does not require authentication and is publicly accessible.
+
+### Response
+
+Returns the HTML feedback form page.
+
+## Static Files
+
+Additional static files (CSS, JavaScript, images) can be accessed at:
+
+```
+GET /v1/media/feedback/<filename>
+```
+
+Replace `<filename>` with the path to the static resource relative to the static directory.
+
+## Development
+
+The static website files are stored in:
+
+```
+services/v1/media/feedback/static/
+```
+
+This directory contains:
+
+- `index.html` - Main HTML file
+- `css/styles.css` - Stylesheet
+- `js/script.js` - JavaScript code
+- `images/` - Directory for image assets
+
+To modify the feedback page, edit these files directly.

docs/media/generate_ass.md

@@ -0,0 +1,350 @@
+# ASS Subtitle Generation Endpoint (v1)
+
+## 1. Overview
+
+The `/v1/media/generate/ass` endpoint is part of the Media API and is responsible for generating an ASS (Advanced SubStation Alpha) subtitle file from a media file (typically a video or audio). It accepts a media URL and various styling options for the subtitles. The endpoint utilizes the `generate_ass_captions_v1` service to generate the ASS file, which is then uploaded to cloud storage, and the cloud URL is returned in the response.
+
+## 2. Endpoint
+
+**URL:** `/v1/media/generate/ass`
+**Method:** `POST`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key`: Required. The API key for authentication.
+
+### Body Parameters
+
+The request body must be a JSON object with the following properties:
+> **Note:** `canvas_width` and `canvas_height` are recommended for audio files (e.g., MP3) to control the subtitle canvas size.
+
+- `media_url` (string, required): The URL of the media file (video or audio) to generate subtitles for.
+- `canvas_width` (integer, optional): Subtitle canvas width in pixels.
+- `canvas_height` (integer, optional): Subtitle canvas height in pixels.
+- `settings` (object, optional): An object containing various styling options for the subtitles. See the schema below for available options.
+- `replace` (array, optional): An array of objects with `find` and `replace` properties, specifying text replacements to be made in the subtitles.
+- `exclude_time_ranges` (array, optional): List of time ranges to skip when generating subtitles. Each item must be an object with:
+  - `start`: (string, required) The start time of the excluded range, as a string timecode in `hh:mm:ss.ms` format (e.g., `00:01:23.456`).
+  - `end`: (string, required) The end time, as a string timecode in `hh:mm:ss.ms` format, which must be strictly greater than `start`.
+- `language` (string, optional): The language code for the subtitles (e.g., "en", "fr"). Defaults to "auto".
+- `webhook_url` (string, optional): A URL to receive a webhook notification when the subtitle generation process is complete.
+- `id` (string, optional): An identifier for the request.
+
+
+
+#### Settings Schema
+
+```json
+{
+    "type": "object",
+    "properties": {
+        "line_color": {"type": "string"},
+        "word_color": {"type": "string"},
+        "outline_color": {"type": "string"},
+        "all_caps": {"type": "boolean"},
+        "max_words_per_line": {"type": "integer"},
+        "x": {"type": "integer"},
+        "y": {"type": "integer"},
+        "position": {
+            "type": "string",
+            "enum": [
+                "bottom_left", "bottom_center", "bottom_right",
+                "middle_left", "middle_center", "middle_right",
+                "top_left", "top_center", "top_right"
+            ]
+        },
+        "alignment": {
+            "type": "string",
+            "enum": ["left", "center", "right"]
+        },
+        "font_family": {"type": "string"},
+        "font_size": {"type": "integer"},
+        "bold": {"type": "boolean"},
+        "italic": {"type": "boolean"},
+        "underline": {"type": "boolean"},
+        "strikeout": {"type": "boolean"},
+        "style": {
+            "type": "string",
+            "enum": [
+                "classic",     // Regular subtitle with all text displayed at once
+                "karaoke",     // Highlights words sequentially in a karaoke style
+                "highlight",   // Shows full text but highlights the current word
+                "underline",   // Shows full text but underlines the current word
+                "word_by_word" // Shows one word at a time
+            ]
+        },
+        "outline_width": {"type": "integer"},
+        "spacing": {"type": "integer"},
+        "angle": {"type": "integer"},
+        "shadow_offset": {"type": "integer"}
+    },
+    "additionalProperties": false
+}
+```
+
+### Example Requests
+
+#### Example 1: Basic Automatic Subtitle Generation
+```json
+{
+    "media_url": "https://example.com/video.mp4"
+}
+```
+This minimal request will automatically transcribe the media and generate white subtitles at the bottom center.
+
+#### Example 2: Custom Styling
+```json
+{
+    "media_url": "https://example.com/video.mp4",
+    "settings": {
+        "style": "classic",
+        "line_color": "#FFFFFF",
+        "outline_color": "#000000",
+        "position": "bottom_center",
+        "alignment": "center",
+        "font_family": "Arial",
+        "font_size": 24,
+        "bold": true
+    }
+}
+```
+
+#### Example 3: Karaoke-Style Subtitles with Advanced Options
+```json
+{
+    "media_url": "https://example.com/video.mp4",
+    "settings": {
+        "line_color": "#FFFFFF",
+        "word_color": "#FFFF00",
+        "outline_color": "#000000",
+        "all_caps": false,
+        "max_words_per_line": 10,
+        "position": "bottom_center",
+        "alignment": "center",
+        "font_family": "Arial",
+        "font_size": 24,
+        "bold": false,
+        "italic": false,
+        "style": "karaoke",
+        "outline_width": 2,
+        "shadow_offset": 2
+    },
+    "replace": [
+        {
+            "find": "um",
+            "replace": ""
+        },
+        {
+            "find": "like",
+            "replace": ""
+        }
+    ],
+    "webhook_url": "https://example.com/webhook",
+    "id": "request-123",
+    "language": "en"
+}
+```
+
+#### Example 4: Excluding Time Ranges from Subtitle Generation
+```json
+{
+    "media_url": "https://example.com/video.mp4",
+    "settings": {
+        "style": "classic",
+        "line_color": "#FFFFFF",
+        "outline_color": "#000000",
+        "position": "bottom_center",
+        "font_family": "Arial",
+        "font_size": 24
+    },
+    "exclude_time_ranges": [
+        { "start": "00:00:10.000", "end": "00:00:20.000" },
+        { "start": "00:00:30.000", "end": "00:00:40.000" }
+    ]
+}
+```
+
+#### Example 5: Generating Subtitles for an MP3 (Audio) File
+```json
+{
+    "canvas_width": 1280,
+    "canvas_height": 720,
+    "media_url": "https://example.com/audio.mp3",
+    "settings": {
+        "style": "classic",
+        "font_family": "Arial",
+        "font_size": 32,
+        "line_color": "#FFFFFF",
+        "outline_color": "#000000"
+    }
+}
+```
+
+
+```bash
+curl -X POST \
+     -H "x-api-key: YOUR_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{
+        "media_url": "https://example.com/video.mp4",
+        "settings": {
+            "line_color": "#FFFFFF",
+            "word_color": "#FFFF00",
+            "outline_color": "#000000",
+            "all_caps": false,
+            "max_words_per_line": 10,
+            "position": "bottom_center",
+            "alignment": "center",
+            "font_family": "Arial",
+            "font_size": 24,
+            "style": "karaoke",
+            "outline_width": 2
+        },
+        "replace": [
+            {
+                "find": "um",
+                "replace": ""
+            }
+        ],
+        "id": "custom-request-id"
+    }' \
+    https://your-api-endpoint.com/v1/media/generate/ass
+```
+
+## 4. Response
+
+### Success Response
+
+The response will be a JSON object with the following properties:
+
+- `code` (integer): The HTTP status code (200 for success).
+- `id` (string): The request identifier, if provided in the request.
+- `job_id` (string): A unique identifier for the job.
+- `response` (string): The cloud URL of the generated ASS subtitle file.
+- `message` (string): A success message.
+- `pid` (integer): The process ID of the worker that processed the request.
+- `queue_id` (integer): The ID of the queue used for processing the request.
+- `run_time` (float): The time taken to process the request (in seconds).
+- `queue_time` (float): The time the request spent in the queue (in seconds).
+- `total_time` (float): The total time taken for the request (in seconds).
+- `queue_length` (integer): The current length of the processing queue.
+- `build_number` (string): The build number of the application.
+
+Example:
+
+```json
+{
+    "code": 200,
+    "id": "request-123",
+    "job_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
+    "response": "https://cloud.example.com/generated-subtitles.ass",
+    "message": "success",
+    "pid": 12345,
+    "queue_id": 140682639937472,
+    "run_time": 2.345,
+    "queue_time": 0.010,
+    "total_time": 2.355,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+#### Missing or Invalid Parameters
+
+**Status Code:** 400 Bad Request
+
+```json
+{
+    "code": 400,
+    "id": "request-123",
+    "job_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
+    "message": "Missing or invalid parameters",
+    "pid": 12345,
+    "queue_id": 140682639937472,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+#### Font Error
+
+**Status Code:** 400 Bad Request
+
+```json
+{
+    "code": 400,
+    "error": "The requested font 'InvalidFont' is not available. Please choose from the available fonts.",
+    "available_fonts": ["Arial", "Times New Roman", "Courier New", ...],
+    "pid": 12345,
+    "queue_id": 140682639937472,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+#### Internal Server Error
+
+**Status Code:** 500 Internal Server Error
+
+```json
+{
+    "code": 500,
+    "id": "request-123",
+    "job_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
+    "error": "An unexpected error occurred during the subtitle generation process.",
+    "pid": 12345,
+    "queue_id": 140682639937472,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+## 5. Error Handling
+
+The endpoint handles the following common errors:
+
+- **Missing or Invalid Parameters**: If any required parameters are missing or invalid, a 400 Bad Request error is returned with a descriptive error message.
+- **Font Error**: If the requested font is not available, a 400 Bad Request error is returned with a list of available fonts.
+- **Internal Server Error**: If an unexpected error occurs during the subtitle generation process, a 500 Internal Server Error is returned with an error message.
+
+Additionally, the main application context (`app.py`) includes error handling for queue overload. If the maximum queue length (`MAX_QUEUE_LENGTH`) is set and the queue size reaches that limit, a 429 Too Many Requests error is returned with a descriptive message.
+
+## 6. Usage Notes
+
+- The `media_url` parameter must be a valid URL pointing to a video or audio file.
+- The `settings` parameter allows for customization of the subtitle appearance and behavior:
+  - `style` determines how subtitles are displayed, with options including:
+    - `classic`: Regular subtitle with all text displayed at once
+    - `karaoke`: Highlights words sequentially in a karaoke style as they're spoken
+    - `highlight`: Shows the full subtitle text but highlights each word as it's spoken
+    - `underline`: Shows the full subtitle text but underlines each word as it's spoken
+    - `word_by_word`: Shows only one word at a time
+  - `position` can be used to place subtitles in one of nine positions on the screen
+  - `alignment` determines text alignment within the position (left, center, right)
+  - `font_family` can be any available system font
+  - Color options can be set using hex codes (e.g., "#FFFFFF" for white)
+- The `replace` parameter can be used to perform text replacements in the subtitles (useful for correcting words or censoring content).
+- The `webhook_url` parameter is optional and can be used to receive a notification when the subtitle generation process is complete.
+- The `id` parameter is optional and can be used to identify the request in webhook responses.
+- The `language` parameter is optional and can be used to specify the language of the subtitles for transcription. If not provided, the language will be automatically detected.
+- The `exclude_time_ranges` parameter can be used to specify time ranges to be excluded from subtitle generation.
+- If either `canvas_width` or `canvas_height` is provided, both must be provided and must be greater than 0.
+
+## 7. Common Issues
+
+- Providing an invalid or inaccessible `media_url`.
+- Requesting an unavailable font in the `settings` object.
+- Using this endpoint with an audio-only file (e.g., MP3) and not providing both `canvas_width` and `canvas_height`. For audio files, you must specify both dimensions to generate a valid ASS subtitle file.
+- Exceeding the maximum queue length, resulting in a 429 Too Many Requests error.
+
+## 8. Best Practices
+
+- Validate the `media_url` parameter before sending the request to ensure it points to a valid and accessible media file.
+- Use the `webhook_url` parameter to receive notifications about the subtitle generation process, rather than polling the API for updates.
+- Provide descriptive and meaningful `id` values to easily identify requests in logs and responses.
+- Use the `replace` parameter judiciously to avoid unintended text replacements in the subtitles.
+- Consider caching the generated ASS files for frequently requested media to improve performance and reduce processing time.

docs/media/media_transcribe.md

@@ -0,0 +1,270 @@
+# Media Transcription API Documentation
+
+## Overview
+The Media Transcription endpoint is part of the v1 API suite, providing audio/video transcription and translation capabilities. This endpoint leverages a queuing system for handling long-running transcription tasks, with webhook support for asynchronous processing. It's integrated into the main Flask application as a Blueprint and supports both direct response and cloud storage options for the transcription results.
+
+## Endpoint
+- **URL**: `/v1/media/transcribe`
+- **Method**: `POST`
+- **Blueprint**: `v1_media_transcribe_bp`
+
+## Request
+
+### Headers
+- `x-api-key`: Required. Authentication key for API access.
+- `Content-Type`: Required. Must be `application/json`.
+
+### Body Parameters
+
+#### Required Parameters
+- `media_url` (string)
+  - Format: URI
+  - Description: URL of the media file to be transcribed
+
+#### Optional Parameters
+- `task` (string)
+  - Allowed values: `"transcribe"`, `"translate"`
+  - Default: `"transcribe"`
+  - Description: Specifies whether to transcribe or translate the audio
+  
+- `include_text` (boolean)
+  - Default: `true`
+  - Description: Include plain text transcription in the response
+  
+- `include_srt` (boolean)
+  - Default: `false`
+  - Description: Include SRT format subtitles in the response
+  
+- `include_segments` (boolean)
+  - Default: `false`
+  - Description: Include timestamped segments in the response
+  
+- `word_timestamps` (boolean)
+  - Default: `false`
+  - Description: Include timestamps for individual words
+  
+- `response_type` (string)
+  - Allowed values: `"direct"`, `"cloud"`
+  - Default: `"direct"`
+  - Description: Whether to return results directly or as cloud storage URLs
+  
+- `language` (string)
+  - Optional
+  - Description: Source language code for transcription
+  
+- `webhook_url` (string)
+  - Format: URI
+  - Description: URL to receive the transcription results asynchronously
+  
+- `id` (string)
+  - Description: Custom identifier for the transcription job
+
+- `max_words_per_line` (integer)
+  - Minimum: 1
+  - Description: Controls the maximum number of words per line in the SRT file. When specified, each segment's text will be split into multiple lines with at most the specified number of words per line.
+
+### Example Request
+
+```bash
+curl -X POST "https://api.example.com/v1/media/transcribe" \
+  -H "x-api-key: your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "media_url": "https://example.com/media/file.mp3",
+    "task": "transcribe",
+    "include_text": true,
+    "include_srt": true,
+    "include_segments": true,
+    "response_type": "cloud",
+    "webhook_url": "https://your-webhook.com/callback",
+    "id": "custom-job-123",
+    "max_words_per_line": 5
+  }'
+```
+
+## Response
+
+### Immediate Response (202 Accepted)
+When a webhook URL is provided, the API returns an immediate acknowledgment:
+
+```json
+{
+  "code": 202,
+  "id": "custom-job-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "processing",
+  "pid": 12345,
+  "queue_id": 67890,
+  "max_queue_length": "unlimited",
+  "queue_length": 1,
+  "build_number": "1.0.0"
+}
+```
+
+### Success Response (via Webhook)
+For direct response_type:
+
+```json
+{
+  "endpoint": "/v1/transcribe/media",
+  "code": 200,
+  "id": "custom-job-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "response": {
+    "text": "Transcribed text content...",
+    "srt": "SRT formatted content...",
+    "segments": [...],
+    "text_url": null,
+    "srt_url": null,
+    "segments_url": null
+  },
+  "message": "success",
+  "pid": 12345,
+  "queue_id": 67890,
+  "run_time": 5.234,
+  "queue_time": 0.123,
+  "total_time": 5.357,
+  "queue_length": 0,
+  "build_number": "1.0.0"
+}
+```
+
+For cloud response_type:
+
+```json
+{
+  "endpoint": "/v1/transcribe/media",
+  "code": 200,
+  "id": "custom-job-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "response": {
+    "text": null,
+    "srt": null,
+    "segments": null,
+    "text_url": "https://storage.example.com/text.txt",
+    "srt_url": "https://storage.example.com/subtitles.srt",
+    "segments_url": "https://storage.example.com/segments.json"
+  },
+  "message": "success",
+  "pid": 12345,
+  "queue_id": 67890,
+  "run_time": 5.234,
+  "queue_time": 0.123,
+  "total_time": 5.357,
+  "queue_length": 0,
+  "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+#### Queue Full (429 Too Many Requests)
+```json
+{
+  "code": 429,
+  "id": "custom-job-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "MAX_QUEUE_LENGTH (100) reached",
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 100,
+  "build_number": "1.0.0"
+}
+```
+
+#### Server Error (500 Internal Server Error)
+```json
+{
+  "endpoint": "/v1/transcribe/media",
+  "code": 500,
+  "id": "custom-job-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "response": null,
+  "message": "Error message details",
+  "pid": 12345,
+  "queue_id": 67890,
+  "run_time": 0.123,
+  "queue_time": 0.056,
+  "total_time": 0.179,
+  "queue_length": 1,
+  "build_number": "1.0.0"
+}
+```
+
+## Error Handling
+
+### Common Errors
+- **Invalid API Key**: 401 Unauthorized
+- **Invalid JSON Payload**: 400 Bad Request
+- **Missing Required Fields**: 400 Bad Request
+- **Invalid media_url**: 400 Bad Request
+- **Queue Full**: 429 Too Many Requests
+- **Processing Error**: 500 Internal Server Error
+
+### Validation Errors
+The endpoint performs strict validation of the request payload using JSON Schema. Common validation errors include:
+- Invalid URI format for media_url or webhook_url
+- Invalid task value (must be "transcribe" or "translate")
+- Invalid response_type value (must be "direct" or "cloud")
+- Unknown properties in the request body
+
+## Usage Notes
+
+1. **Webhook Processing**
+   - When a webhook_url is provided, the request is processed asynchronously
+   - The API returns an immediate 202 response with a job_id
+   - Final results are sent to the webhook_url when processing completes
+
+2. **Queue Management**
+   - Requests with webhook_url are queued for processing
+   - MAX_QUEUE_LENGTH environment variable controls queue size
+   - Set MAX_QUEUE_LENGTH to 0 for unlimited queue size
+
+3. **File Management**
+   - For cloud response_type, temporary files are automatically cleaned up
+   - Results are uploaded to cloud storage before deletion
+   - URLs in the response provide access to the stored files
+
+4. **SRT Formatting**
+   - The `max_words_per_line` parameter allows control over the maximum number of words per line in the SRT file
+   - When specified, each segment's text will be split into multiple lines with at most the specified number of words per line
+   - This is useful for creating more readable subtitles with consistent line lengths
+
+## Common Issues
+
+1. **Media Access**
+   - Ensure media_url is publicly accessible
+   - Verify media file format is supported
+   - Check for media file corruption
+
+2. **Webhook Delivery**
+   - Ensure webhook_url is publicly accessible
+   - Implement webhook endpoint retry logic
+   - Monitor webhook endpoint availability
+
+3. **Resource Usage**
+   - Large media files may take significant processing time
+   - Monitor queue length for production deployments
+   - Consider implementing request size limits
+
+## Best Practices
+
+1. **Request Handling**
+   - Always provide a unique id for job tracking
+   - Implement webhook retry logic
+   - Store job_id for result correlation
+
+2. **Resource Management**
+   - Monitor queue length in production
+   - Implement appropriate timeout handling
+   - Use cloud response_type for large files
+
+3. **Error Handling**
+   - Implement comprehensive webhook error handling
+   - Log job_id with all related operations
+   - Monitor processing times and error rates
+
+4. **Security**
+   - Use HTTPS for media_url and webhook_url
+   - Implement webhook authentication
+   - Validate media file types before processing

docs/media/metadata.md

@@ -0,0 +1,156 @@
+# Media Metadata
+
+This endpoint extracts detailed metadata from media files (video, audio, image) including format, duration, codec information, resolution, and bitrates.
+
+## Endpoint
+
+`POST /v1/media/metadata`
+
+## Authentication
+
+This endpoint requires API authentication. See [Authentication](../toolkit/authenticate.md) for details.
+
+## Request
+
+```json
+{
+  "media_url": "https://example.com/media.mp4",
+  "webhook_url": "https://example.com/webhook",  // Optional
+  "id": "custom-id"  // Optional
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| media_url | string | Yes | URL of the media file to analyze |
+| webhook_url | string | No | URL to receive the processing result |
+| id | string | No | Custom identifier for tracking the request |
+
+## Response
+
+**Success (200 OK)**
+
+```json
+{
+  "code": 200,
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "id": "custom-id",
+  "response": {
+    "filesize": 15679283,
+    "filesize_mb": 14.95,
+    "duration": 87.46,
+    "duration_formatted": "00:01:27.46",
+    "format": "mp4,mov,m4a,3gp,3g2,mj2",
+    "overall_bitrate": 1438692,
+    "overall_bitrate_mbps": 1.44,
+    "has_video": true,
+    "video_codec": "h264",
+    "video_codec_long": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
+    "width": 1920,
+    "height": 1080,
+    "resolution": "1920x1080",
+    "fps": 30.0,
+    "video_bitrate": 1300000,
+    "video_bitrate_mbps": 1.3,
+    "pixel_format": "yuv420p",
+    "has_audio": true,
+    "audio_codec": "aac",
+    "audio_codec_long": "AAC (Advanced Audio Coding)",
+    "audio_channels": 2,
+    "audio_sample_rate": 48000,
+    "audio_sample_rate_khz": 48.0,
+    "audio_bitrate": 128000,
+    "audio_bitrate_kbps": 128
+  },
+  "message": "success",
+  "run_time": 0.542,
+  "queue_time": 0,
+  "total_time": 0.542,
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 0,
+  "build_number": "123"
+}
+```
+
+For audio-only files, video-related fields will not be included. Similarly, for video files without audio, audio-related fields will not be included.
+
+**Queued (202 Accepted)**
+
+```json
+{
+  "code": 202,
+  "id": "custom-id",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "processing",
+  "pid": 12345,
+  "queue_id": 67890,
+  "max_queue_length": "unlimited",
+  "queue_length": 0,
+  "build_number": "123"
+}
+```
+
+**Error (4xx/5xx)**
+
+```json
+{
+  "code": 500,
+  "id": "custom-id",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "Error extracting metadata: [error details]",
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 0,
+  "build_number": "123"
+}
+```
+
+## Example
+
+### Request
+
+```bash
+curl -X POST https://api.example.com/v1/media/metadata \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your_api_key" \
+  -d '{
+    "media_url": "https://example.com/sample-video.mp4",
+    "webhook_url": "https://your-server.com/webhook"
+  }'
+```
+
+### Response
+
+```json
+{
+  "code": 200,
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "response": {
+    "filesize": 15679283,
+    "filesize_mb": 14.95,
+    "duration": 87.46,
+    "duration_formatted": "00:01:27.46",
+    "format": "mp4",
+    "overall_bitrate": 1438692,
+    "overall_bitrate_mbps": 1.44,
+    "has_video": true,
+    "video_codec": "h264",
+    "width": 1920,
+    "height": 1080,
+    "resolution": "1920x1080",
+    "fps": 30.0,
+    "video_bitrate": 1300000,
+    "video_bitrate_mbps": 1.3,
+    "has_audio": true,
+    "audio_codec": "aac",
+    "audio_channels": 2,
+    "audio_sample_rate": 48000,
+    "audio_bitrate": 128000,
+    "audio_bitrate_kbps": 128
+  },
+  "message": "success",
+  "run_time": 0.542,
+  "total_time": 0.542
+}
+```

docs/media/silence.md

@@ -0,0 +1,176 @@
+# Silence Detection Endpoint
+
+## 1. Overview
+
+The `/v1/media/silence` endpoint is part of the Media API and is designed to detect silence intervals in a given media file. It takes a media URL, along with various parameters for configuring the silence detection process, and returns the detected silence intervals. This endpoint fits into the overall API structure as a part of the version 1 (v1) media-related endpoints.
+
+## 2. Endpoint
+
+```
+POST /v1/media/silence
+```
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+The request body should be a JSON object with the following parameters:
+
+- `media_url` (required, string): The URL of the media file to be processed.
+- `start` (optional, string): The start time for the silence detection process, in the format `HH:MM:SS.ms`. If not provided, the process will start from the beginning of the media file.
+- `end` (optional, string): The end time for the silence detection process, in the format `HH:MM:SS.ms`. If not provided, the process will continue until the end of the media file.
+- `noise` (optional, string): The noise threshold for silence detection, in decibels (dB). Default is `-30dB`.
+- `duration` (required, number): The minimum duration (in seconds) for a silence interval to be considered valid.
+- `mono` (optional, boolean): Whether to process the audio as mono (single channel) or not. Default is `true`.
+- `webhook_url` (required, string): The URL to which the response should be sent as a webhook.
+- `id` (required, string): A unique identifier for the request.
+
+The `validate_payload` directive in the routes file enforces the following JSON schema for the request body:
+
+```python
+{
+    "type": "object",
+    "properties": {
+        "media_url": {"type": "string", "format": "uri"},
+        "start": {"type": "string"},
+        "end": {"type": "string"},
+        "noise": {"type": "string"},
+        "duration": {"type": "number", "minimum": 0.1},
+        "mono": {"type": "boolean"},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["media_url", "duration"],
+    "additionalProperties": False
+}
+```
+
+### Example Request
+
+```json
+{
+    "media_url": "https://example.com/audio.mp3",
+    "start": "00:00:10.0",
+    "end": "00:01:00.0",
+    "noise": "-25dB",
+    "duration": 0.5,
+    "mono": false,
+    "webhook_url": "https://example.com/webhook",
+    "id": "unique-request-id"
+}
+```
+
+```
+curl -X POST \
+  https://api.example.com/v1/media/silence \
+  -H 'x-api-key: YOUR_API_KEY' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "media_url": "https://example.com/audio.mp3",
+    "start": "00:00:10.0",
+    "end": "00:01:00.0",
+    "noise": "-25dB",
+    "duration": 0.5,
+    "mono": false,
+    "webhook_url": "https://example.com/webhook",
+    "id": "unique-request-id"
+}'
+```
+
+## 4. Response
+
+### Success Response
+
+The success response will be sent as a webhook to the specified `webhook_url`. The response format follows the general response structure defined in the main application context (`app.py`). Here's an example:
+
+```json
+{
+    "endpoint": "/v1/media/silence",
+    "code": 200,
+    "id": "unique-request-id",
+    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+    "response": [
+        {
+            "start": 10.5,
+            "end": 15.2
+        },
+        {
+            "start": 20.0,
+            "end": 25.7
+        }
+    ],
+    "message": "success",
+    "pid": 12345,
+    "queue_id": 1234567890,
+    "run_time": 1.234,
+    "queue_time": 0.123,
+    "total_time": 1.357,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+- **400 Bad Request**: This error is returned when the request body is missing or contains invalid parameters. Example response:
+
+```json
+{
+    "code": 400,
+    "message": "Invalid request payload"
+}
+```
+
+- **401 Unauthorized**: This error is returned when the `x-api-key` header is missing or invalid. Example response:
+
+```json
+{
+    "code": 401,
+    "message": "Unauthorized"
+}
+```
+
+- **500 Internal Server Error**: This error is returned when an unexpected error occurs during the silence detection process. Example response:
+
+```json
+{
+    "code": 500,
+    "message": "An error occurred during the silence detection process"
+}
+```
+
+## 5. Error Handling
+
+The endpoint handles the following common errors:
+
+- Missing or invalid request parameters: Returns a 400 Bad Request error.
+- Missing or invalid `x-api-key` header: Returns a 401 Unauthorized error.
+- Unexpected exceptions during the silence detection process: Returns a 500 Internal Server Error.
+
+The main application context (`app.py`) also includes error handling for situations where the task queue has reached its maximum length (`MAX_QUEUE_LENGTH`). In such cases, a 429 Too Many Requests error is returned.
+
+## 6. Usage Notes
+
+- The `media_url` parameter should point to a valid media file that can be processed by the silence detection service.
+- The `start` and `end` parameters are optional and can be used to specify a time range within the media file for silence detection.
+- The `noise` parameter allows you to adjust the noise threshold for silence detection. Lower values (e.g., `-40dB`) will detect more silence intervals, while higher values (e.g., `-20dB`) will detect fewer silence intervals.
+- The `duration` parameter specifies the minimum duration (in seconds) for a silence interval to be considered valid. This can be useful for filtering out very short silence intervals that may not be relevant.
+- The `mono` parameter determines whether the audio should be processed as a single channel (mono) or multiple channels (stereo or surround).
+
+## 7. Common Issues
+
+- Providing an invalid or inaccessible `media_url`.
+- Specifying `start` and `end` times that are outside the duration of the media file.
+- Setting the `duration` parameter to an unreasonably low value, which may result in detecting too many short silence intervals.
+
+## 8. Best Practices
+
+- Validate the `media_url` parameter to ensure it points to a valid and accessible media file.
+- Consider using the `start` and `end` parameters to focus the silence detection on a specific time range within the media file, if needed.
+- Adjust the `noise` and `duration` parameters based on your specific use case and requirements for silence detection.
+- If you need to process stereo or surround audio, set the `mono` parameter to `false`.
+- Monitor the response from the endpoint to ensure that the silence detection process completed successfully and that the detected silence intervals meet your expectations.

docs/s3/upload.md

@@ -0,0 +1,66 @@
+# S3 Upload API
+
+This endpoint allows you to stream a file from a remote URL directly to an S3-compatible storage service without using local disk space.
+
+## Endpoint
+
+`POST /v1/s3/upload`
+
+## Authentication
+
+This endpoint requires an API key to be provided in the `X-API-Key` header.
+
+## Request Body
+
+The request body should be a JSON object with the following properties:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| file_url | string | Yes | The URL of the file to upload to S3 |
+| filename | string | No | Custom filename to use for the uploaded file. If not provided, the original filename will be used |
+| public | boolean | No | Whether to make the file publicly accessible. Defaults to `false` |
+
+Example request body:
+```json
+{
+  "file_url": "https://example.com/path/to/file.mp4",
+  "filename": "custom-name.mp4",
+  "public": true
+}
+```
+
+## Response
+
+The response will be a JSON object with the following properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| url | string | The URL of the uploaded file. For public files, this is a direct URL. For private files, this is a pre-signed URL that will expire after 1 hour |
+| filename | string | The filename of the uploaded file |
+| bucket | string | The name of the S3 bucket where the file was uploaded |
+| public | boolean | Whether the file is publicly accessible |
+
+Example response:
+```json
+{
+  "url": "https://bucket-name.s3.region.amazonaws.com/custom-name.mp4",
+  "filename": "custom-name.mp4",
+  "bucket": "bucket-name",
+  "public": true
+}
+```
+
+## Error Handling
+
+If an error occurs, the response will include an error message with an appropriate HTTP status code.
+
+## Technical Details
+
+This endpoint uses the S3-compatible multipart upload API to stream the file directly from the source URL to S3 without saving it locally. This allows for efficient transfer of large files with minimal memory usage.
+
+The implementation:
+1. Streams the file from the source URL in chunks
+2. Uploads each chunk to S3 as a part of a multipart upload
+3. Completes the multipart upload once all parts are uploaded
+
+This approach supports resumable uploads and can handle large files efficiently.

docs/toolkit/authenticate.md

@@ -0,0 +1,92 @@
+# Authenticate Endpoint
+
+## 1. Overview
+
+The `/v1/toolkit/authenticate` endpoint is a part of the `v1_toolkit_auth` blueprint in the API structure. Its purpose is to authenticate requests by verifying the provided API key against a predefined value. This endpoint serves as a gatekeeper, ensuring that only authorized clients can access the API's resources.
+
+## 2. Endpoint
+
+- URL Path: `/v1/toolkit/authenticate`
+- HTTP Method: `GET`
+
+## 3. Request
+
+### Headers
+
+- `X-API-Key` (required): The API key used for authentication.
+
+### Body Parameters
+
+This endpoint does not require any request body parameters.
+
+### Example Request
+
+```bash
+curl -X GET -H "X-API-Key: YOUR_API_KEY" http://localhost:8080/v1/toolkit/authenticate
+```
+
+## 4. Response
+
+### Success Response
+
+If the provided API key matches the predefined value, the endpoint will return a 200 OK status code with the following response:
+
+```json
+{
+  "code": 200,
+  "endpoint": "/authenticate",
+  "id": null,
+  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+  "message": "success",
+  "pid": 12345,
+  "queue_id": 1234567890,
+  "queue_length": 0,
+  "response": "Authorized",
+  "run_time": 0.001,
+  "total_time": 0.001,
+  "queue_time": 0,
+  "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+If the provided API key is invalid or missing, the endpoint will return a 401 Unauthorized status code with the following response:
+
+```json
+{
+  "code": 401,
+  "endpoint": "/authenticate",
+  "id": null,
+  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+  "message": "Unauthorized",
+  "pid": 12345,
+  "queue_id": 1234567890,
+  "queue_length": 0,
+  "response": null,
+  "run_time": 0.001,
+  "total_time": 0.001,
+  "queue_time": 0,
+  "build_number": "1.0.0"
+}
+```
+
+## 5. Error Handling
+
+The main error that can occur with this endpoint is providing an invalid or missing API key. In this case, the endpoint will return a 401 Unauthorized status code with an appropriate error message.
+
+## 6. Usage Notes
+
+- This endpoint is designed to be used as a gatekeeper for the API, ensuring that only authorized clients can access the API's resources.
+- The API key should be kept secure and should not be shared with unauthorized parties.
+
+## 7. Common Issues
+
+- Forgetting to include the `X-API-Key` header in the request.
+- Using an invalid or expired API key.
+
+## 8. Best Practices
+
+- Rotate API keys periodically to enhance security.
+- Store API keys securely and avoid committing them to version control systems.
+- Consider implementing additional security measures, such as rate limiting or IP whitelisting, to further protect the API.

docs/toolkit/job_status.md

@@ -0,0 +1,141 @@
+# Job Status Endpoint Documentation
+
+## 1. Overview
+
+The `/v1/toolkit/job/status` endpoint is part of the Toolkit API and is used to retrieve the status of a specific job. It fits into the overall API structure as a utility endpoint for monitoring and managing jobs submitted to the various media processing endpoints.
+
+## 2. Endpoint
+
+**URL Path:** `/v1/toolkit/job/status`
+**HTTP Method:** `POST`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+The request body must be a JSON object with the following parameter:
+
+- `job_id` (string, required): The unique identifier of the job for which the status is requested.
+
+The `validate_payload` directive in the routes file enforces the following JSON schema for the request body:
+
+```python
+{
+    "type": "object",
+    "properties": {
+        "job_id": {
+            "type": "string"
+        }
+    },
+    "required": ["job_id"],
+}
+```
+
+### Example Request
+
+```json
+{
+    "job_id": "e6d7f3c0-9c9f-4b8a-b7c3-f0e3c9f6b9d7"
+}
+```
+
+```bash
+curl -X POST \
+     -H "x-api-key: YOUR_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{"job_id": "e6d7f3c0-9c9f-4b8a-b7c3-f0e3c9f6b9d7"}' \
+     http://your-api-endpoint/v1/toolkit/job/status
+```
+
+## 4. Response
+
+### Success Response
+
+The success response will contain the job status file content directly, as shown in the example response from `app.py`:
+
+```json
+{
+    "endpoint": "/v1/toolkit/job/status",
+    "code": 200,
+    "id": null,
+    "job_id": "e6d7f3c0-9c9f-4b8a-b7c3-f0e3c9f6b9d7",
+    "response": {
+        "job_status": "done",
+        "job_id": "e6d7f3c0-9c9f-4b8a-b7c3-f0e3c9f6b9d7",
+        "queue_id": 140368864456064,
+        "process_id": 123456,
+        "response": {
+            "endpoint": "/v1/media/transcribe",
+            "code": 200,
+            "id": "transcribe_job_123",
+            "job_id": "e6d7f3c0-9c9f-4b8a-b7c3-f0e3c9f6b9d7",
+            "response": "Transcription completed successfully.",
+            "message": "success",
+            "pid": 123456,
+            "queue_id": 140368864456064,
+            "run_time": 5.234,
+            "queue_time": 1.123,
+            "total_time": 6.357,
+            "queue_length": 0,
+            "build_number": "1.0.0"
+        }
+    },
+    "message": "success",
+    "pid": 123456,
+    "queue_id": 140368864456064,
+    "run_time": 0.001,
+    "queue_time": 0.0,
+    "total_time": 0.001,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+- **404 Not Found**: If the job with the provided `job_id` is not found, the response will be:
+
+```json
+{
+    "error": "Job not found",
+    "job_id": "e6d7f3c0-9c9f-4b8a-b7c3-f0e3c9f6b9d7"
+}
+```
+
+- **500 Internal Server Error**: If an unexpected error occurs while retrieving the job status, the response will be:
+
+```json
+{
+    "error": "Failed to retrieve job status: <error_message>",
+    "code": 500
+}
+```
+
+## 5. Error Handling
+
+- **Missing or Invalid Parameters**: If the `job_id` parameter is missing or invalid, the request will be rejected with a 400 Bad Request error.
+- **Job Not Found**: If the job with the provided `job_id` is not found, a 404 Not Found error will be returned.
+- **Unexpected Errors**: Any unexpected errors that occur during the retrieval of the job status will result in a 500 Internal Server Error response.
+
+The main application context (`app.py`) includes error handling for queue overflow situations, where a 429 Too Many Requests error is returned if the maximum queue length is reached.
+
+## 6. Usage Notes
+
+- Ensure that you have a valid API key for authentication.
+- The `job_id` parameter must be a valid UUID string representing an existing job.
+- This endpoint does not perform any media processing; it only retrieves the status of a previously submitted job.
+
+## 7. Common Issues
+
+- Providing an invalid or non-existent `job_id`.
+- Attempting to retrieve the status of a job that has already been processed and removed from the system.
+
+## 8. Best Practices
+
+- Use this endpoint to monitor the progress of long-running jobs or to check the status of completed jobs.
+- Implement proper error handling in your client application to handle different error scenarios, such as job not found or unexpected errors.
+- Consider rate-limiting or implementing a queue system on the client side to avoid overwhelming the API with too many requests.

docs/toolkit/jobs_status.md

@@ -0,0 +1,141 @@
+# Get All Jobs Status
+
+## 1. Overview
+
+The `/v1/toolkit/jobs/status` endpoint is part of the Toolkit API and is used to retrieve the status of all jobs within a specified time range. This endpoint fits into the overall API structure by providing a way to monitor and manage the jobs that have been submitted to the system. It is a part of the `v1_toolkit_jobs_status_bp` blueprint, which is registered in the main `app.py` file.
+
+## 2. Endpoint
+
+**URL Path:** `/v1/toolkit/jobs/status`
+**HTTP Method:** `POST`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+- `since_seconds` (optional, number): The number of seconds to look back for jobs. If not provided, the default value is 600 seconds (10 minutes).
+
+The JSON payload is completely optional. If no payload is provided or if the payload is empty, the endpoint will use the default value of 600 seconds.
+
+### Example Request
+
+```json
+{
+    "since_seconds": 3600
+}
+```
+
+Or with no body:
+
+```bash
+curl -X POST \
+     -H "x-api-key: YOUR_API_KEY" \
+     -H "Content-Type: application/json" \
+     http://your-api-url/v1/toolkit/jobs/status
+```
+
+With body:
+
+```bash
+curl -X POST \
+     -H "x-api-key: YOUR_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{"since_seconds": 3600}' \
+     http://your-api-url/v1/toolkit/jobs/status
+```
+
+## 4. Response
+
+### Success Response
+
+The response will be a JSON object containing the job statuses for all jobs within the specified time range. The response format follows the general response structure defined in `app.py`.
+
+```json
+{
+    "code": 200,
+    "id": null,
+    "job_id": "job_id_value",
+    "response": {
+        "job_id_1": "job_status_1",
+        "job_id_2": "job_status_2",
+        ...
+    },
+    "message": "success",
+    "run_time": 0.123,
+    "queue_time": 0,
+    "total_time": 0.123,
+    "pid": 12345,
+    "queue_id": 1234567890,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+- **404 Not Found**: If the jobs directory is not found.
+
+```json
+{
+    "code": 404,
+    "id": null,
+    "job_id": "job_id_value",
+    "response": null,
+    "message": "Jobs directory not found",
+    "run_time": 0.123,
+    "queue_time": 0,
+    "total_time": 0.123,
+    "pid": 12345,
+    "queue_id": 1234567890,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+- **500 Internal Server Error**: If an exception occurs while retrieving the job statuses.
+
+```json
+{
+    "code": 500,
+    "id": null,
+    "job_id": "job_id_value",
+    "response": null,
+    "message": "Failed to retrieve job statuses: Error message",
+    "run_time": 0.123,
+    "queue_time": 0,
+    "total_time": 0.123,
+    "pid": 12345,
+    "queue_id": 1234567890,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+## 5. Error Handling
+
+- Missing or invalid `x-api-key` header: The `authenticate` decorator will return a 401 Unauthorized error.
+- Jobs directory not found: The endpoint will return a 404 Not Found error if the jobs directory is not found.
+- Exception during job status retrieval: The endpoint will return a 500 Internal Server Error if an exception occurs while retrieving the job statuses.
+
+The main `app.py` file includes error handling for queue overflow (429 Too Many Requests) and logging of job statuses (queued, running, done) using the `log_job_status` function.
+
+## 6. Usage Notes
+
+- This endpoint is useful for monitoring the status of jobs submitted to the system, especially when dealing with long-running or queued jobs.
+- The `since_seconds` parameter can be adjusted to retrieve job statuses within a specific time range, allowing for more targeted monitoring.
+
+## 7. Common Issues
+
+- Providing an invalid `x-api-key` header will result in an authentication error.
+- If the jobs directory is not found or an exception occurs during job status retrieval, the endpoint will return an error.
+
+## 8. Best Practices
+
+- Always include the `x-api-key` header with a valid API key for authentication.
+- Monitor the job statuses regularly to keep track of the progress and completion of submitted jobs.
+- Adjust the `since_seconds` parameter based on your monitoring requirements to retrieve job statuses within a specific time range.
+- Implement error handling and logging mechanisms to track and troubleshoot any issues that may arise.

docs/toolkit/test.md

@@ -0,0 +1,89 @@
+# NCA Toolkit Test API Endpoint
+
+## 1. Overview
+
+The `/v1/toolkit/test` endpoint is a part of the NCA Toolkit API and is designed to test the API setup. It creates a temporary file, uploads it to cloud storage, and then returns the upload URL. This endpoint serves as a simple test to ensure that the API is properly configured and can perform basic file operations and cloud storage interactions.
+
+## 2. Endpoint
+
+**URL Path:** `/v1/toolkit/test`
+**HTTP Method:** `GET`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+This endpoint does not require any request body parameters.
+
+### Example Request
+
+```bash
+curl -X GET \
+  https://your-api-url.com/v1/toolkit/test \
+  -H 'x-api-key: your-api-key'
+```
+
+## 4. Response
+
+### Success Response
+
+```json
+{
+  "endpoint": "/v1/toolkit/test",
+  "code": 200,
+  "id": null,
+  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+  "response": "https://cloud-storage.com/success.txt",
+  "message": "success",
+  "pid": 12345,
+  "queue_id": 67890,
+  "run_time": 0.123,
+  "queue_time": 0.0,
+  "total_time": 0.123,
+  "queue_length": 0,
+  "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+**Status Code: 401 Unauthorized**
+
+```json
+{
+  "code": 401,
+  "message": "Unauthorized: Invalid or missing API key"
+}
+```
+
+**Status Code: 500 Internal Server Error**
+
+```json
+{
+  "code": 500,
+  "message": "An error occurred while processing the request"
+}
+```
+
+## 5. Error Handling
+
+- **Missing or Invalid API Key (401 Unauthorized)**: If the `x-api-key` header is missing or invalid, the API will return a 401 Unauthorized error.
+- **Internal Server Error (500)**: If an unexpected error occurs during the file creation, upload, or any other operation, the API will return a 500 Internal Server Error with the error message.
+
+## 6. Usage Notes
+
+This endpoint is primarily used for testing purposes and does not require any specific input parameters. It can be called to verify that the API is set up correctly and can perform basic operations.
+
+## 7. Common Issues
+
+- Incorrect or missing API key: Ensure that the `x-api-key` header is included with a valid API key.
+- Temporary file creation or upload issues: If there are any issues with creating or uploading the temporary file, the API will return an error.
+
+## 8. Best Practices
+
+- Use this endpoint during the initial setup and testing phase of the API integration to ensure that the API is configured correctly.
+- Regularly test the API setup using this endpoint to catch any potential issues or configuration changes that may affect the API's functionality.

docs/video/caption_video.md

@@ -0,0 +1,354 @@
+# Video Captioning Endpoint (v1)
+
+## 1. Overview
+
+The `/v1/video/caption` endpoint is part of the Video API and is responsible for adding captions to a video file. It accepts a video URL, caption text, and various styling options for the captions. The endpoint utilizes the `process_captioning_v1` service to generate a captioned video file, which is then uploaded to cloud storage, and the cloud URL is returned in the response.
+
+## 2. Endpoint
+
+**URL:** `/v1/video/caption`
+**Method:** `POST`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key`: Required. The API key for authentication.
+
+### Body Parameters
+
+The request body must be a JSON object with the following properties:
+
+- `video_url` (string, required): The URL of the video file to be captioned.
+- `captions` (string, optional): Can be one of the following:
+  - Raw caption text to be added to the video
+  - URL to an SRT subtitle file
+  - URL to an ASS subtitle file
+  - If not provided, the system will automatically generate captions by transcribing the audio from the video
+- `settings` (object, optional): An object containing various styling options for the captions. See the schema below for available options.
+- `replace` (array, optional): An array of objects with `find` and `replace` properties, specifying text replacements to be made in the captions.
+- `webhook_url` (string, optional): A URL to receive a webhook notification when the captioning process is complete.
+- `id` (string, optional): An identifier for the request.
+- `language` (string, optional): The language code for the captions (e.g., "en", "fr"). Defaults to "auto".
+- `exclude_time_ranges` (array, optional): List of time ranges to skip when adding captions. Each item must be an object with:
+  - `start`: (string, required) The start time of the excluded range, as a string timecode in `hh:mm:ss.ms` format (e.g., `00:01:23.456`).
+  - `end`: (string, required) The end time, as a string timecode in `hh:mm:ss.ms` format, which must be strictly greater than `start`.
+  If either value is not a valid timecode string, or if `end` is not greater than `start`, the request will return an error.
+
+#### Settings Schema
+
+```json
+{
+    "type": "object",
+    "properties": {
+        "line_color": {"type": "string"},
+        "word_color": {"type": "string"},
+        "outline_color": {"type": "string"},
+        "all_caps": {"type": "boolean"},
+        "max_words_per_line": {"type": "integer"},
+        "x": {"type": "integer"},
+        "y": {"type": "integer"},
+        "position": {
+            "type": "string",
+            "enum": [
+                "bottom_left", "bottom_center", "bottom_right",
+                "middle_left", "middle_center", "middle_right",
+                "top_left", "top_center", "top_right"
+            ]
+        },
+        "alignment": {
+            "type": "string",
+            "enum": ["left", "center", "right"]
+        },
+        "font_family": {"type": "string"},
+        "font_size": {"type": "integer"},
+        "bold": {"type": "boolean"},
+        "italic": {"type": "boolean"},
+        "underline": {"type": "boolean"},
+        "strikeout": {"type": "boolean"},
+        "style": {
+            "type": "string",
+            "enum": [
+                "classic",     // Regular captioning with all text displayed at once
+                "karaoke",     // Highlights words sequentially in a karaoke style
+                "highlight",   // Shows full text but highlights the current word
+                "underline",   // Shows full text but underlines the current word
+                "word_by_word" // Shows one word at a time
+            ]
+        },
+        "outline_width": {"type": "integer"},
+        "spacing": {"type": "integer"},
+        "angle": {"type": "integer"},
+        "shadow_offset": {"type": "integer"}
+    },
+    "additionalProperties": false
+}
+```
+
+### Example Requests
+
+#### Example 1: Basic Automatic Captioning
+```json
+{
+    "video_url": "https://example.com/video.mp4"
+}
+```
+This minimal request will automatically transcribe the video and add white captions at the bottom center.
+
+#### Example 2: Custom Text with Styling
+```json
+{
+    "video_url": "https://example.com/video.mp4",
+    "captions": "This is a sample caption text.",
+    "settings": {
+        "style": "classic",
+        "line_color": "#FFFFFF",
+        "outline_color": "#000000",
+        "position": "bottom_center",
+        "alignment": "center",
+        "font_family": "Arial",
+        "font_size": 24,
+        "bold": true
+    }
+}
+```
+
+#### Example 3: Karaoke-Style Captions with Advanced Options
+```json
+{
+    "video_url": "https://example.com/video.mp4",
+    "settings": {
+        "line_color": "#FFFFFF",
+        "word_color": "#FFFF00",
+        "outline_color": "#000000",
+        "all_caps": false,
+        "max_words_per_line": 10,
+        "position": "bottom_center",
+        "alignment": "center",
+        "font_family": "Arial",
+        "font_size": 24,
+        "bold": false,
+        "italic": false,
+        "style": "karaoke",
+        "outline_width": 2,
+        "shadow_offset": 2
+    },
+    "replace": [
+        {
+            "find": "um",
+            "replace": ""
+        },
+        {
+            "find": "like",
+            "replace": ""
+        }
+    ],
+    "webhook_url": "https://example.com/webhook",
+    "id": "request-123",
+    "language": "en"
+}
+```
+
+#### Example 4: Using an External Subtitle File
+```json
+{
+    "video_url": "https://example.com/video.mp4",
+    "captions": "https://example.com/subtitles.srt",
+    "settings": {
+        "line_color": "#FFFFFF",
+        "outline_color": "#000000",
+        "position": "bottom_center",
+        "font_family": "Arial",
+        "font_size": 24
+    }
+}
+```
+
+#### Example 5: Excluding Time Ranges from Captioning
+```json
+{
+    "video_url": "https://example.com/video.mp4",
+    "settings": {
+        "style": "classic",
+        "line_color": "#FFFFFF",
+        "outline_color": "#000000",
+        "position": "bottom_center",
+        "font_family": "Arial",
+        "font_size": 24
+    },
+    "exclude_time_ranges": [
+        { "start": "00:00:10.000", "end": "00:00:20.000" },
+        { "start": "00:00:30.000", "end": "00:00:40.000" }
+    ]
+}
+```
+
+```bash
+curl -X POST \
+     -H "x-api-key: YOUR_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{
+        "video_url": "https://example.com/video.mp4",
+        "settings": {
+            "line_color": "#FFFFFF",
+            "word_color": "#FFFF00",
+            "outline_color": "#000000",
+            "all_caps": false,
+            "max_words_per_line": 10,
+            "position": "bottom_center",
+            "alignment": "center",
+            "font_family": "Arial",
+            "font_size": 24,
+            "style": "karaoke",
+            "outline_width": 2
+        },
+        "replace": [
+            {
+                "find": "um",
+                "replace": ""
+            }
+        ],
+        "id": "custom-request-id"
+    }' \
+    https://your-api-endpoint.com/v1/video/caption
+```
+
+## 4. Response
+
+### Success Response
+
+The response will be a JSON object with the following properties:
+
+- `code` (integer): The HTTP status code (200 for success).
+- `id` (string): The request identifier, if provided in the request.
+- `job_id` (string): A unique identifier for the job.
+- `response` (string): The cloud URL of the captioned video file.
+- `message` (string): A success message.
+- `pid` (integer): The process ID of the worker that processed the request.
+- `queue_id` (integer): The ID of the queue used for processing the request.
+- `run_time` (float): The time taken to process the request (in seconds).
+- `queue_time` (float): The time the request spent in the queue (in seconds).
+- `total_time` (float): The total time taken for the request (in seconds).
+- `queue_length` (integer): The current length of the processing queue.
+- `build_number` (string): The build number of the application.
+
+Example:
+
+```json
+{
+    "code": 200,
+    "id": "request-123",
+    "job_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
+    "response": "https://cloud.example.com/captioned-video.mp4",
+    "message": "success",
+    "pid": 12345,
+    "queue_id": 140682639937472,
+    "run_time": 5.234,
+    "queue_time": 0.012,
+    "total_time": 5.246,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+#### Missing or Invalid Parameters
+
+**Status Code:** 400 Bad Request
+
+```json
+{
+    "code": 400,
+    "id": "request-123",
+    "job_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
+    "message": "Missing or invalid parameters",
+    "pid": 12345,
+    "queue_id": 140682639937472,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+#### Font Error
+
+**Status Code:** 400 Bad Request
+
+```json
+{
+    "code": 400,
+    "error": "The requested font 'InvalidFont' is not available. Please choose from the available fonts.",
+    "available_fonts": ["Arial", "Times New Roman", "Courier New", ...],
+    "pid": 12345,
+    "queue_id": 140682639937472,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+#### Internal Server Error
+
+**Status Code:** 500 Internal Server Error
+
+```json
+{
+    "code": 500,
+    "id": "request-123",
+    "job_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
+    "error": "An unexpected error occurred during the captioning process.",
+    "pid": 12345,
+    "queue_id": 140682639937472,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+## 5. Error Handling
+
+The endpoint handles the following common errors:
+
+- **Missing or Invalid Parameters**: If any required parameters are missing or invalid, a 400 Bad Request error is returned with a descriptive error message.
+- **Font Error**: If the requested font is not available, a 400 Bad Request error is returned with a list of available fonts.
+- **Internal Server Error**: If an unexpected error occurs during the captioning process, a 500 Internal Server Error is returned with an error message.
+
+Additionally, the main application context (`app.py`) includes error handling for queue overload. If the maximum queue length (`MAX_QUEUE_LENGTH`) is set and the queue size reaches that limit, a 429 Too Many Requests error is returned with a descriptive message.
+
+## 6. Usage Notes
+
+- The `video_url` parameter must be a valid URL pointing to a video file (MP4, MOV, etc.).
+- The `captions` parameter is optional and can be used in multiple ways:
+  - If not provided, the endpoint will automatically transcribe the audio and generate captions
+  - If provided as plain text, the text will be used as captions for the entire video
+  - If provided as a URL to an SRT or ASS subtitle file, the system will use that file for captioning
+  - For SRT files, only 'classic' style is supported
+  - For ASS files, the original styling will be preserved
+- The `settings` parameter allows for customization of the caption appearance and behavior:
+  - `style` determines how captions are displayed, with options including:
+    - `classic`: Regular captioning with all text displayed at once
+    - `karaoke`: Highlights words sequentially in a karaoke style as they're spoken
+    - `highlight`: Shows the full caption text but highlights each word as it's spoken
+    - `underline`: Shows the full caption text but underlines each word as it's spoken
+    - `word_by_word`: Shows only one word at a time
+  - `position` can be used to place captions in one of nine positions on the screen
+  - `alignment` determines text alignment within the position (left, center, right)
+  - `font_family` can be any available system font
+  - Color options can be set using hex codes (e.g., "#FFFFFF" for white)
+- The `replace` parameter can be used to perform text replacements in the captions (useful for correcting words or censoring content).
+- The `webhook_url` parameter is optional and can be used to receive a notification when the captioning process is complete.
+- The `id` parameter is optional and can be used to identify the request in webhook responses.
+- The `language` parameter is optional and can be used to specify the language of the captions for transcription. If not provided, the language will be automatically detected.
+- The `exclude_time_ranges` parameter can be used to specify time ranges to be excluded from captioning.
+
+## 7. Common Issues
+
+- Providing an invalid or inaccessible `video_url`.
+- Requesting an unavailable font in the `settings` object.
+- Exceeding the maximum queue length, resulting in a 429 Too Many Requests error.
+
+## 8. Best Practices
+
+- Validate the `video_url` parameter before sending the request to ensure it points to a valid and accessible video file.
+- Use the `webhook_url` parameter to receive notifications about the captioning process, rather than polling the API for updates.
+- Provide descriptive and meaningful `id` values to easily identify requests in logs and responses.
+- Use the `replace` parameter judiciously to avoid unintended text replacements in the captions.
+- Consider caching the captioned video files for frequently requested videos to improve performance and reduce processing time.

docs/video/concatenate.md

@@ -0,0 +1,180 @@
+# Video Concatenation Endpoint
+
+## 1. Overview
+
+The `/v1/video/concatenate` endpoint is a part of the Video API and is responsible for combining multiple video files into a single video file. This endpoint fits into the overall API structure as a part of the version 1 (v1) routes, specifically under the `/v1/video` namespace.
+
+## 2. Endpoint
+
+**URL Path:** `/v1/video/concatenate`
+**HTTP Method:** `POST`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+The request body must be a JSON object with the following properties:
+
+- `video_urls` (required, array of objects): An array of video URLs to be concatenated. Each object in the array must have a `video_url` property (string, URI format) containing the URL of the video file.
+- `webhook_url` (optional, string, URI format): The URL to which the response should be sent as a webhook.
+- `id` (optional, string): An identifier for the request.
+
+The `validate_payload` decorator in the routes file enforces the following JSON schema for the request body:
+
+```json
+{
+    "type": "object",
+    "properties": {
+        "video_urls": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "video_url": {"type": "string", "format": "uri"}
+                },
+                "required": ["video_url"]
+            },
+            "minItems": 1
+        },
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["video_urls"],
+    "additionalProperties": False
+}
+```
+
+### Example Request
+
+```json
+{
+    "video_urls": [
+        {"video_url": "https://example.com/video1.mp4"},
+        {"video_url": "https://example.com/video2.mp4"},
+        {"video_url": "https://example.com/video3.mp4"}
+    ],
+    "webhook_url": "https://example.com/webhook",
+    "id": "request-123"
+}
+```
+
+```bash
+curl -X POST \
+     -H "x-api-key: YOUR_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{
+        "video_urls": [
+            {"video_url": "https://example.com/video1.mp4"},
+            {"video_url": "https://example.com/video2.mp4"},
+            {"video_url": "https://example.com/video3.mp4"}
+        ],
+        "webhook_url": "https://example.com/webhook",
+        "id": "request-123"
+     }' \
+     https://your-api-endpoint.com/v1/video/concatenate
+```
+
+## 4. Response
+
+### Success Response
+
+The success response follows the general response format defined in the `app.py` file. Here's an example:
+
+```json
+{
+    "endpoint": "/v1/video/concatenate",
+    "code": 200,
+    "id": "request-123",
+    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+    "response": "https://cloud-storage.example.com/combined-video.mp4",
+    "message": "success",
+    "pid": 12345,
+    "queue_id": 6789,
+    "run_time": 10.234,
+    "queue_time": 2.345,
+    "total_time": 12.579,
+    "queue_length": 0,
+    "build_number": "1.0.0"
+}
+```
+
+The `response` field contains the URL of the combined video file uploaded to cloud storage.
+
+### Error Responses
+
+- **400 Bad Request**: Returned when the request body is missing or invalid.
+
+  ```json
+  {
+    "code": 400,
+    "message": "Invalid request payload"
+  }
+  ```
+
+- **401 Unauthorized**: Returned when the `x-api-key` header is missing or invalid.
+
+  ```json
+  {
+    "code": 401,
+    "message": "Unauthorized"
+  }
+  ```
+
+- **429 Too Many Requests**: Returned when the maximum queue length is reached.
+
+  ```json
+  {
+    "code": 429,
+    "id": "request-123",
+    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+    "message": "MAX_QUEUE_LENGTH (100) reached",
+    "pid": 12345,
+    "queue_id": 6789,
+    "queue_length": 100,
+    "build_number": "1.0.0"
+  }
+  ```
+
+- **500 Internal Server Error**: Returned when an unexpected error occurs during the video concatenation process.
+
+  ```json
+  {
+    "code": 500,
+    "message": "An error occurred during video concatenation"
+  }
+  ```
+
+## 5. Error Handling
+
+The endpoint handles the following common errors:
+
+- **Missing or invalid request body**: If the request body is missing or does not conform to the expected JSON schema, a 400 Bad Request error is returned.
+- **Missing or invalid API key**: If the `x-api-key` header is missing or invalid, a 401 Unauthorized error is returned.
+- **Queue length exceeded**: If the maximum queue length is reached (determined by the `MAX_QUEUE_LENGTH` environment variable), a 429 Too Many Requests error is returned.
+- **Unexpected errors during video concatenation**: If an unexpected error occurs during the video concatenation process, a 500 Internal Server Error is returned with the error message.
+
+The main application context (`app.py`) also includes error handling for the task queue. If the queue length exceeds the `MAX_QUEUE_LENGTH` limit, the request is rejected with a 429 Too Many Requests error.
+
+## 6. Usage Notes
+
+- The video files to be concatenated must be accessible via the provided URLs.
+- The order of the video files in the `video_urls` array determines the order in which they will be concatenated.
+- If the `webhook_url` parameter is provided, the response will be sent as a webhook to the specified URL.
+- The `id` parameter can be used to identify the request in the response.
+
+## 7. Common Issues
+
+- Providing invalid or inaccessible video URLs.
+- Exceeding the maximum queue length, which can lead to requests being rejected with a 429 Too Many Requests error.
+- Encountering unexpected errors during the video concatenation process, which can result in a 500 Internal Server Error.
+
+## 8. Best Practices
+
+- Validate the video URLs before sending the request to ensure they are accessible and in the correct format.
+- Monitor the queue length and adjust the `MAX_QUEUE_LENGTH` value accordingly to prevent requests from being rejected due to a full queue.
+- Implement retry mechanisms for handling temporary errors or failures during the video concatenation process.
+- Provide meaningful and descriptive `id` values to easily identify requests in the response.

docs/video/cut.md

@@ -0,0 +1,197 @@
+# Video Cut Endpoint
+
+## 1. Overview
+
+The `/v1/video/cut` endpoint is part of the Video API and allows users to cut specified segments from a video file with optional encoding settings. This endpoint fits into the overall API structure as a part of the version 1 (`v1`) routes, specifically under the `video` category.
+
+## 2. Endpoint
+
+```
+POST /v1/video/cut
+```
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+The request body must be a JSON object with the following properties:
+
+- `video_url` (required, string): The URL of the video file to be cut.
+- `cuts` (required, array of objects): An array of cut segments, where each object has the following properties:
+  - `start` (required, string): The start time of the cut segment in the format `hh:mm:ss.ms`.
+  - `end` (required, string): The end time of the cut segment in the format `hh:mm:ss.ms`.
+- `video_codec` (optional, string): The video codec to use for encoding the output video. Default is `libx264`.
+- `video_preset` (optional, string): The video preset to use for encoding the output video. Default is `medium`.
+- `video_crf` (optional, number): The Constant Rate Factor (CRF) value for video encoding. Must be between 0 and 51. Default is 23.
+- `audio_codec` (optional, string): The audio codec to use for encoding the output video. Default is `aac`.
+- `audio_bitrate` (optional, string): The audio bitrate to use for encoding the output video. Default is `128k`.
+- `webhook_url` (optional, string): The URL to receive a webhook notification when the job is completed.
+- `id` (optional, string): A unique identifier for the request.
+
+### Example Request
+
+```json
+{
+  "video_url": "https://example.com/video.mp4",
+  "cuts": [
+    {
+      "start": "00:00:10.000",
+      "end": "00:00:20.000"
+    },
+    {
+      "start": "00:00:30.000",
+      "end": "00:00:40.000"
+    }
+  ],
+  "video_codec": "libx264",
+  "video_preset": "medium",
+  "video_crf": 23,
+  "audio_codec": "aac",
+  "audio_bitrate": "128k",
+  "webhook_url": "https://example.com/webhook",
+  "id": "unique-request-id"
+}
+```
+
+```bash
+curl -X POST \
+  https://api.example.com/v1/video/cut \
+  -H 'x-api-key: YOUR_API_KEY' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "video_url": "https://example.com/video.mp4",
+    "cuts": [
+      {
+        "start": "00:00:10.000",
+        "end": "00:00:20.000"
+      },
+      {
+        "start": "00:00:30.000",
+        "end": "00:00:40.000"
+      }
+    ],
+    "video_codec": "libx264",
+    "video_preset": "medium",
+    "video_crf": 23,
+    "audio_codec": "aac",
+    "audio_bitrate": "128k",
+    "webhook_url": "https://example.com/webhook",
+    "id": "unique-request-id"
+  }'
+```
+
+## 4. Response
+
+### Success Response
+
+The response follows the general response format defined in the main application context (`app.py`). Here's an example of a successful response:
+
+```json
+{
+  "endpoint": "/v1/video/cut",
+  "code": 200,
+  "id": "unique-request-id",
+  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+  "response": "https://example.com/processed-video.mp4",
+  "message": "success",
+  "pid": 12345,
+  "queue_id": 6789,
+  "run_time": 5.234,
+  "queue_time": 0.123,
+  "total_time": 5.357,
+  "queue_length": 0,
+  "build_number": "1.0.0"
+}
+```
+
+The `response` field contains the URL of the processed video file.
+
+### Error Responses
+
+- **400 Bad Request**
+
+  ```json
+  {
+    "code": 400,
+    "message": "Invalid request payload"
+  }
+  ```
+
+  This error occurs when the request payload is missing required fields or contains invalid data.
+
+- **401 Unauthorized**
+
+  ```json
+  {
+    "code": 401,
+    "message": "Invalid API key"
+  }
+  ```
+
+  This error occurs when the provided `x-api-key` header is missing or invalid.
+
+- **429 Too Many Requests**
+
+  ```json
+  {
+    "code": 429,
+    "id": "unique-request-id",
+    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+    "message": "MAX_QUEUE_LENGTH (100) reached",
+    "pid": 12345,
+    "queue_id": 6789,
+    "queue_length": 100,
+    "build_number": "1.0.0"
+  }
+  ```
+
+  This error occurs when the maximum queue length has been reached, and the request cannot be processed immediately.
+
+- **500 Internal Server Error**
+
+  ```json
+  {
+    "code": 500,
+    "message": "An error occurred during video processing"
+  }
+  ```
+
+  This error occurs when an unexpected error occurs during the video processing or encoding.
+
+## 5. Error Handling
+
+The endpoint handles the following common errors:
+
+- **Missing or invalid request parameters**: If any required parameters are missing or invalid, the endpoint returns a 400 Bad Request error with an appropriate error message.
+- **Invalid API key**: If the provided `x-api-key` header is missing or invalid, the endpoint returns a 401 Unauthorized error.
+- **Queue limit reached**: If the maximum queue length has been reached, the endpoint returns a 429 Too Many Requests error with the current queue length and the maximum queue length.
+- **Unexpected errors during video processing**: If an unexpected error occurs during the video processing or encoding, the endpoint returns a 500 Internal Server Error with a generic error message.
+
+The main application context (`app.py`) also includes error handling for the queue system and webhook notifications.
+
+## 6. Usage Notes
+
+- The `video_url` parameter must be a valid URL that points to a video file accessible by the server.
+- The `cuts` parameter must be an array of objects, where each object represents a cut segment with a start and end time in the format `hh:mm:ss.ms`.
+- The optional encoding parameters (`video_codec`, `video_preset`, `video_crf`, `audio_codec`, `audio_bitrate`) allow you to customize the encoding settings for the output video file.
+- If the `webhook_url` parameter is provided, the server will send a webhook notification to the specified URL when the job is completed.
+- The `id` parameter can be used to associate the request with a unique identifier for tracking purposes.
+
+## 7. Common Issues
+
+- Providing an invalid or inaccessible `video_url`.
+- Specifying overlapping or invalid cut segments in the `cuts` parameter.
+- Providing invalid encoding settings that are not supported by the server.
+- Reaching the maximum queue length, which can cause requests to be rejected with a 429 Too Many Requests error.
+
+## 8. Best Practices
+
+- Validate the `video_url` parameter before sending the request to ensure it points to a valid and accessible video file.
+- Ensure that the cut segments in the `cuts` parameter are correctly formatted and do not overlap or exceed the duration of the video.
+- Use the optional encoding parameters judiciously, as they can impact the processing time and output video quality.
+- Implement retry mechanisms for handling 429 Too Many Requests errors, as the queue length may fluctuate over time.
+- Monitor the webhook notifications or poll the server for job status updates to track the progress of long-running jobs.

docs/video/split.md

@@ -0,0 +1,173 @@
+# Video Split Endpoint
+
+## 1. Overview
+
+The `/v1/video/split` endpoint is part of the Video API and is used to split a video file into multiple segments based on specified start and end times. This endpoint fits into the overall API structure as a part of the version 1 (`v1`) routes, specifically under the `video` category.
+
+## 2. Endpoint
+
+**URL Path:** `/v1/video/split`
+**HTTP Method:** `POST`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+The request body must be a JSON object with the following properties:
+
+- `video_url` (required, string): The URL of the video file to be split.
+- `splits` (required, array of objects): An array of objects specifying the start and end times for each split. Each object must have the following properties:
+  - `start` (required, string): The start time of the split in the format `hh:mm:ss.ms`.
+  - `end` (required, string): The end time of the split in the format `hh:mm:ss.ms`.
+- `video_codec` (optional, string): The video codec to use for encoding the split videos. Default is `libx264`.
+- `video_preset` (optional, string): The video preset to use for encoding the split videos. Default is `medium`.
+- `video_crf` (optional, number): The Constant Rate Factor (CRF) value for video encoding. Must be between 0 and 51. Default is 23.
+- `audio_codec` (optional, string): The audio codec to use for encoding the split videos. Default is `aac`.
+- `audio_bitrate` (optional, string): The audio bitrate to use for encoding the split videos. Default is `128k`.
+- `webhook_url` (optional, string): The URL to receive a webhook notification when the split operation is complete.
+- `id` (optional, string): A unique identifier for the request.
+
+### Example Request
+
+```json
+{
+  "video_url": "https://example.com/video.mp4",
+  "splits": [
+    {
+      "start": "00:00:10.000",
+      "end": "00:00:20.000"
+    },
+    {
+      "start": "00:00:30.000",
+      "end": "00:00:40.000"
+    }
+  ],
+  "video_codec": "libx264",
+  "video_preset": "medium",
+  "video_crf": 23,
+  "audio_codec": "aac",
+  "audio_bitrate": "128k",
+  "webhook_url": "https://example.com/webhook",
+  "id": "unique-request-id"
+}
+```
+
+```bash
+curl -X POST \
+  https://api.example.com/v1/video/split \
+  -H 'x-api-key: YOUR_API_KEY' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "video_url": "https://example.com/video.mp4",
+    "splits": [
+      {
+        "start": "00:00:10.000",
+        "end": "00:00:20.000"
+      },
+      {
+        "start": "00:00:30.000",
+        "end": "00:00:40.000"
+      }
+    ],
+    "video_codec": "libx264",
+    "video_preset": "medium",
+    "video_crf": 23,
+    "audio_codec": "aac",
+    "audio_bitrate": "128k",
+    "webhook_url": "https://example.com/webhook",
+    "id": "unique-request-id"
+  }'
+```
+
+## 4. Response
+
+### Success Response
+
+The success response follows the general response format specified in `app.py`. Here's an example:
+
+```json
+{
+  "endpoint": "/v1/video/split",
+  "code": 200,
+  "id": "unique-request-id",
+  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+  "response": [
+    {
+      "file_url": "https://example.com/split-1.mp4"
+    },
+    {
+      "file_url": "https://example.com/split-2.mp4"
+    }
+  ],
+  "message": "success",
+  "pid": 12345,
+  "queue_id": 6789,
+  "run_time": 5.234,
+  "queue_time": 0.123,
+  "total_time": 5.357,
+  "queue_length": 0,
+  "build_number": "1.0.0"
+}
+```
+
+The `response` field contains an array of objects, each representing a split video file. Each object has a `file_url` property containing the URL of the split video file.
+
+### Error Responses
+
+- **400 Bad Request**: Returned when the request payload is missing or invalid.
+- **401 Unauthorized**: Returned when the `x-api-key` header is missing or invalid.
+- **429 Too Many Requests**: Returned when the maximum queue length has been reached.
+- **500 Internal Server Error**: Returned when an unexpected error occurs during the video split process.
+
+Example error response:
+
+```json
+{
+  "code": 400,
+  "id": "unique-request-id",
+  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+  "message": "Invalid request payload: 'splits' is a required property",
+  "pid": 12345,
+  "queue_id": 6789,
+  "queue_length": 2,
+  "build_number": "1.0.0"
+}
+```
+
+## 5. Error Handling
+
+The endpoint handles the following common errors:
+
+- Missing or invalid request parameters: Returns a 400 Bad Request error with a descriptive error message.
+- Authentication failure: Returns a 401 Unauthorized error if the `x-api-key` header is missing or invalid.
+- Queue length exceeded: Returns a 429 Too Many Requests error if the maximum queue length has been reached.
+- Unexpected exceptions: Returns a 500 Internal Server Error with the exception message.
+
+The main application context (`app.py`) also includes error handling for queue length limits and webhook notifications.
+
+## 6. Usage Notes
+
+- The `video_url` parameter must be a valid URL pointing to a video file.
+- The `splits` array must contain at least one object specifying the start and end times for a split.
+- The start and end times must be in the format `hh:mm:ss.ms` (hours:minutes:seconds.milliseconds).
+- The `video_codec`, `video_preset`, `video_crf`, `audio_codec`, and `audio_bitrate` parameters are optional and can be used to customize the encoding settings for the split videos.
+- If the `webhook_url` parameter is provided, a webhook notification will be sent to the specified URL when the split operation is complete.
+- The `id` parameter is optional and can be used to uniquely identify the request.
+
+## 7. Common Issues
+
+- Providing an invalid or inaccessible `video_url`.
+- Specifying overlapping or invalid start and end times in the `splits` array.
+- Exceeding the maximum queue length, which can result in a 429 Too Many Requests error.
+
+## 8. Best Practices
+
+- Validate the `video_url` parameter before sending the request to ensure it points to a valid video file.
+- Ensure that the start and end times in the `splits` array are correctly formatted and do not overlap.
+- Consider using the `webhook_url` parameter to receive notifications about the completion of the split operation, especially for long-running or asynchronous requests.
+- Implement retry mechanisms and error handling in your client application to handle potential errors and failures.
+- Monitor the queue length and adjust the `MAX_QUEUE_LENGTH` environment variable as needed to prevent excessive queuing and potential timeouts.

docs/video/thumbnail.md

@@ -0,0 +1,165 @@
+# Video Thumbnail Generation API
+
+## Overview
+
+The `/v1/video/thumbnail` endpoint allows users to extract a thumbnail image from a specific timestamp in a video. This endpoint is part of the video processing capabilities of the API, which includes other features like video concatenation and captioning. The endpoint processes the request asynchronously using a queue system, uploads the generated thumbnail to cloud storage, and returns the URL of the uploaded image.
+
+## Endpoint
+
+- **URL**: `/v1/video/thumbnail`
+- **Method**: `POST`
+
+## Request
+
+### Headers
+
+- `x-api-key`: Required. Your API authentication key.
+
+### Body Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `video_url` | string (URI format) | Yes | URL of the video from which to extract the thumbnail |
+| `second` | number (minimum: 0) | No | Timestamp in seconds at which to extract the thumbnail (defaults to 0) |
+| `webhook_url` | string (URI format) | No | URL to receive the processing result asynchronously |
+| `id` | string | No | Custom identifier for tracking the request |
+
+### Example Request
+
+```json
+{
+  "video_url": "https://example.com/video.mp4",
+  "second": 30,
+  "webhook_url": "https://your-service.com/webhook",
+  "id": "custom-request-123"
+}
+```
+
+### Example cURL Command
+
+```bash
+curl -X POST \
+  https://api.example.com/v1/video/thumbnail \
+  -H 'Content-Type: application/json' \
+  -H 'x-api-key: your-api-key' \
+  -d '{
+    "video_url": "https://example.com/video.mp4",
+    "second": 30,
+    "webhook_url": "https://your-service.com/webhook",
+    "id": "custom-request-123"
+  }'
+```
+
+## Response
+
+### Immediate Response (Status Code: 202)
+
+When a webhook URL is provided, the API immediately returns a 202 Accepted response and processes the request asynchronously:
+
+```json
+{
+  "code": 202,
+  "id": "custom-request-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "processing",
+  "pid": 12345,
+  "queue_id": 67890,
+  "max_queue_length": "unlimited",
+  "queue_length": 1,
+  "build_number": "1.0.0"
+}
+```
+
+### Success Response (Status Code: 200)
+
+When no webhook URL is provided or when the webhook is called after processing:
+
+```json
+{
+  "code": 200,
+  "id": "custom-request-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "response": "https://storage.example.com/thumbnails/video-thumbnail-123.jpg",
+  "message": "success",
+  "run_time": 1.234,
+  "queue_time": 0.567,
+  "total_time": 1.801,
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 0,
+  "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+#### Invalid Request (Status Code: 400)
+
+```json
+{
+  "code": 400,
+  "message": "Invalid request: 'video_url' is a required property",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+#### Queue Full (Status Code: 429)
+
+```json
+{
+  "code": 429,
+  "id": "custom-request-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "MAX_QUEUE_LENGTH (100) reached",
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 100,
+  "build_number": "1.0.0"
+}
+```
+
+#### Server Error (Status Code: 500)
+
+```json
+{
+  "code": 500,
+  "id": "custom-request-123",
+  "job_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "Failed to download video from provided URL",
+  "pid": 12345,
+  "queue_id": 67890,
+  "queue_length": 0,
+  "build_number": "1.0.0"
+}
+```
+
+## Error Handling
+
+The endpoint handles various error scenarios:
+
+- **Missing Required Parameters**: Returns a 400 error if `video_url` is missing.
+- **Invalid Parameter Format**: Returns a 400 error if parameters don't match the expected format (e.g., invalid URLs).
+- **Queue Capacity**: Returns a 429 error if the processing queue is full.
+- **Processing Errors**: Returns a 500 error if there are issues during thumbnail extraction or upload.
+
+## Usage Notes
+
+1. **Asynchronous Processing**: For long-running operations, provide a `webhook_url` to receive the result asynchronously.
+2. **Timestamp Selection**: Choose an appropriate `second` value to capture a meaningful frame from the video.
+3. **Request Tracking**: Use the `id` parameter to track your requests across your systems.
+4. **Queue Management**: The API uses a queue system with configurable maximum length (set by the `MAX_QUEUE_LENGTH` environment variable).
+
+## Common Issues
+
+1. **Inaccessible Video URLs**: Ensure the video URL is publicly accessible or has proper authentication.
+2. **Invalid Timestamp**: If the specified second exceeds the video duration, the API may use the last frame or return an error.
+3. **Webhook Failures**: If your webhook endpoint is unavailable, you won't receive the processing result.
+4. **Large Videos**: Processing very large videos may take longer and could time out.
+
+## Best Practices
+
+1. **Use Webhooks for Long Videos**: Always use webhooks when processing large videos to avoid HTTP timeout issues.
+2. **Optimize Thumbnail Selection**: Choose meaningful timestamps for thumbnails (e.g., after intro sequences).
+3. **Error Handling**: Implement proper error handling in your application to manage API errors gracefully.
+4. **Rate Limiting**: Monitor the queue length in responses to avoid overwhelming the service.
+5. **Idempotent Requests**: Use the `id` parameter to make requests idempotent and avoid duplicate processing.

docs/video/trim.md

@@ -0,0 +1,147 @@
+# Video Trim Endpoint
+
+## 1. Overview
+
+The `/v1/video/trim` endpoint is part of the Video API and allows users to trim a video by removing specified portions from the beginning and/or end. It also provides optional encoding settings to control the output video quality. This endpoint fits into the overall API structure as a part of the version 1 (`v1`) routes, specifically under the `video` category.
+
+## 2. Endpoint
+
+**URL Path:** `/v1/video/trim`
+**HTTP Method:** `POST`
+
+## 3. Request
+
+### Headers
+
+- `x-api-key` (required): The API key for authentication.
+
+### Body Parameters
+
+- `video_url` (required, string): The URL of the video file to be trimmed.
+- `start` (optional, string): The start time for trimming in the format `hh:mm:ss` or `mm:ss`.
+- `end` (optional, string): The end time for trimming in the format `hh:mm:ss` or `mm:ss`.
+- `video_codec` (optional, string): The video codec to be used for encoding the output video. Default is `libx264`.
+- `video_preset` (optional, string): The video preset to be used for encoding the output video. Default is `medium`.
+- `video_crf` (optional, number): The Constant Rate Factor (CRF) value for video encoding, ranging from 0 to 51. Default is 23.
+- `audio_codec` (optional, string): The audio codec to be used for encoding the output video. Default is `aac`.
+- `audio_bitrate` (optional, string): The audio bitrate to be used for encoding the output video. Default is `128k`.
+- `webhook_url` (optional, string): The URL to receive a webhook notification upon completion of the task.
+- `id` (optional, string): A unique identifier for the request.
+
+The `validate_payload` directive in the routes file ensures that the request payload adheres to the specified schema, which includes the required and optional parameters, their data types, and any additional constraints.
+
+### Example Request
+
+```json
+{
+  "video_url": "https://example.com/video.mp4",
+  "start": "00:01:00",
+  "end": "00:03:00",
+  "video_codec": "libx264",
+  "video_preset": "faster",
+  "video_crf": 28,
+  "audio_codec": "aac",
+  "audio_bitrate": "128k",
+  "webhook_url": "https://example.com/webhook",
+  "id": "unique-request-id"
+}
+```
+
+```bash
+curl -X POST \
+  https://api.example.com/v1/video/trim \
+  -H 'x-api-key: YOUR_API_KEY' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "video_url": "https://example.com/video.mp4",
+    "start": "00:01:00",
+    "end": "00:03:00",
+    "video_codec": "libx264",
+    "video_preset": "faster",
+    "video_crf": 28,
+    "audio_codec": "aac",
+    "audio_bitrate": "128k",
+    "webhook_url": "https://example.com/webhook",
+    "id": "unique-request-id"
+  }'
+```
+
+## 4. Response
+
+### Success Response
+
+The success response follows the general response structure defined in the `app.py` file. Here's an example:
+
+```json
+{
+  "endpoint": "/v1/video/trim",
+  "code": 200,
+  "id": "unique-request-id",
+  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
+  "response": "https://example.com/trimmed-video.mp4",
+  "message": "success",
+  "pid": 12345,
+  "queue_id": 6789,
+  "run_time": 5.234,
+  "queue_time": 0.123,
+  "total_time": 5.357,
+  "queue_length": 0,
+  "build_number": "1.0.0"
+}
+```
+
+### Error Responses
+
+- **400 Bad Request**: Returned when the request payload is missing or contains invalid parameters.
+
+  ```json
+  {
+    "code": 400,
+    "message": "Invalid request payload"
+  }
+  ```
+
+- **401 Unauthorized**: Returned when the `x-api-key` header is missing or invalid.
+
+  ```json
+  {
+    "code": 401,
+    "message": "Unauthorized"
+  }
+  ```
+
+- **500 Internal Server Error**: Returned when an unexpected error occurs during the video trimming process.
+
+  ```json
+  {
+    "code": 500,
+    "message": "An error occurred during the video trimming process"
+  }
+  ```
+
+## 5. Error Handling
+
+The endpoint handles common errors such as missing or invalid parameters by returning appropriate HTTP status codes and error messages. The `validate_payload` decorator ensures that the request payload adheres to the specified schema, and any violations will result in a 400 Bad Request error.
+
+The main application context (`app.py`) includes error handling for the task queue. If the maximum queue length is reached, the endpoint will return a 429 Too Many Requests error with a corresponding message.
+
+## 6. Usage Notes
+
+- The `start` and `end` parameters are optional, but at least one of them must be provided to perform the trimming operation.
+- The `video_codec`, `video_preset`, `video_crf`, `audio_codec`, and `audio_bitrate` parameters are optional and allow users to customize the encoding settings for the output video.
+- The `webhook_url` parameter is optional and can be used to receive a notification when the task is completed.
+- The `id` parameter is optional and can be used to uniquely identify the request.
+
+## 7. Common Issues
+
+- Providing an invalid or inaccessible `video_url`.
+- Specifying invalid or unsupported values for the encoding parameters (`video_codec`, `video_preset`, `video_crf`, `audio_codec`, `audio_bitrate`).
+- Encountering issues with the video trimming process due to unsupported video formats or corrupted files.
+
+## 8. Best Practices
+
+- Validate the `video_url` parameter to ensure it points to a valid and accessible video file.
+- Use appropriate encoding settings based on the desired output quality and file size requirements.
+- Implement error handling and retry mechanisms for failed requests or network issues.
+- Monitor the task queue length and adjust the `MAX_QUEUE_LENGTH` value accordingly to prevent overloading the system.
+- Implement rate limiting or throttling mechanisms to prevent abuse or excessive requests.

routes/audio_mixing.py

@@ -0,0 +1,73 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+from flask import Blueprint
+from app_utils import *
+import logging
+from services.audio_mixing import process_audio_mixing
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+
+audio_mixing_bp = Blueprint('audio_mixing', __name__)
+logger = logging.getLogger(__name__)
+
+@audio_mixing_bp.route('/audio-mixing', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "video_url": {"type": "string", "format": "uri"},
+        "audio_url": {"type": "string", "format": "uri"},
+        "video_vol": {"type": "number", "minimum": 0, "maximum": 100},
+        "audio_vol": {"type": "number", "minimum": 0, "maximum": 100},
+        "output_length": {"type": "string", "enum": ["video", "audio"]},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["video_url", "audio_url"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def audio_mixing(job_id, data):
+    video_url = data.get('video_url')
+    audio_url = data.get('audio_url')
+    video_vol = data.get('video_vol', 100)
+    audio_vol = data.get('audio_vol', 100)
+    output_length = data.get('output_length', 'video')
+    webhook_url = data.get('webhook_url')
+    id = data.get('id')
+
+    logger.info(f"Job {job_id}: Received audio mixing request for {video_url} and {audio_url}")
+
+    try:
+        # Process audio and video mixing
+        output_filename = process_audio_mixing(
+            video_url, audio_url, video_vol, audio_vol, output_length, job_id, webhook_url
+        )
+
+        # Upload the mixed file using the unified upload_file() method
+        cloud_url = upload_file(output_filename)
+
+        logger.info(f"Job {job_id}: Mixed media uploaded to cloud storage: {cloud_url}")
+
+        # Return the cloud URL for the uploaded file
+        return cloud_url, "/audio-mixing", 200
+        
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error during audio mixing process - {str(e)}")
+        return str(e), "/audio-mixing", 500

routes/authenticate.py

@@ -0,0 +1,35 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+from flask import Blueprint, request, jsonify, current_app
+from app_utils import *
+from functools import wraps
+import os
+
+auth_bp = Blueprint('auth', __name__)
+
+API_KEY = os.environ.get('API_KEY')
+
+@auth_bp.route('/authenticate', methods=['GET'])
+@queue_task_wrapper(bypass_queue=True)
+def authenticate_endpoint(**kwargs):
+    api_key = request.headers.get('X-API-Key')
+    if api_key == API_KEY:
+        return "Authorized", "/authenticate", 200
+    else:
+        return "Unauthorized", "/authenticate", 401

routes/caption_video.py

@@ -0,0 +1,92 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+from flask import Blueprint, current_app
+from app_utils import *
+import logging
+from services.caption_video import process_captioning
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+import os
+
+caption_bp = Blueprint('caption', __name__)
+logger = logging.getLogger(__name__)
+
+@caption_bp.route('/caption-video', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "video_url": {"type": "string", "format": "uri"},
+        "srt": {"type": "string"},
+        "ass": {"type": "string"},
+        "options": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "option": {"type": "string"},
+                    "value": {}  # Allow any type for value
+                },
+                "required": ["option", "value"]
+            }
+        },
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["video_url"],
+    "oneOf": [
+        {"required": ["srt"]},
+        {"required": ["ass"]}
+    ],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def caption_video(job_id, data):
+    video_url = data['video_url']
+    caption_srt = data.get('srt')
+    caption_ass = data.get('ass')
+    options = data.get('options', [])
+    webhook_url = data.get('webhook_url')
+    id = data.get('id')
+
+    logger.info(f"Job {job_id}: Received captioning request for {video_url}")
+    logger.info(f"Job {job_id}: Options received: {options}")
+
+    if caption_ass is not None:
+        captions = caption_ass
+        caption_type = "ass"
+    else:
+        captions = caption_srt
+        caption_type = "srt"
+
+    try:
+        output_filename = process_captioning(video_url, captions, caption_type, options, job_id)
+        logger.info(f"Job {job_id}: Captioning process completed successfully")
+
+        # Upload the captioned video using the unified upload_file() method
+        cloud_url = upload_file(output_filename)
+
+        logger.info(f"Job {job_id}: Captioned video uploaded to cloud storage: {cloud_url}")
+
+        # Return the cloud URL for the uploaded file
+        return cloud_url, "/caption-video", 200
+
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error during captioning process - {str(e)}", exc_info=True)
+        return str(e), "/caption-video", 500

routes/combine_videos.py

@@ -0,0 +1,70 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+from flask import Blueprint
+from app_utils import *
+import logging
+from services.ffmpeg_toolkit import process_video_combination
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+
+combine_bp = Blueprint('combine', __name__)
+logger = logging.getLogger(__name__)
+
+@combine_bp.route('/combine-videos', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "video_urls": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "video_url": {"type": "string", "format": "uri"}
+                },
+                "required": ["video_url"]
+            },
+            "minItems": 1
+        },
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["video_urls"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def combine_videos(job_id, data):
+    media_urls = data['video_urls']
+    webhook_url = data.get('webhook_url')
+    id = data.get('id')
+
+    logger.info(f"Job {job_id}: Received combine-videos request for {len(media_urls)} videos")
+
+    try:
+        output_file = process_video_combination(media_urls, job_id)
+        logger.info(f"Job {job_id}: Video combination process completed successfully")
+
+        cloud_url = upload_file(output_file)
+        logger.info(f"Job {job_id}: Combined video uploaded to cloud storage: {cloud_url}")
+
+        return cloud_url, "/combine-videos", 200
+
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error during video combination process - {str(e)}")
+        return str(e), "/combine-videos", 500

routes/extract_keyframes.py

@@ -0,0 +1,66 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+from flask import Blueprint
+from app_utils import *
+import logging
+from services.extract_keyframes import process_keyframe_extraction
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+
+extract_keyframes_bp = Blueprint('extract_keyframes', __name__)
+logger = logging.getLogger(__name__)
+
+@extract_keyframes_bp.route('/extract-keyframes', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "video_url": {"type": "string", "format": "uri"},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["video_url"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def extract_keyframes(job_id, data):
+    video_url = data.get('video_url')
+    webhook_url = data.get('webhook_url')
+    id = data.get('id')
+
+    logger.info(f"Job {job_id}: Received keyframe extraction request for {video_url}")
+
+    try:
+        # Process keyframe extraction
+        image_paths = process_keyframe_extraction(video_url, job_id)
+
+        # Upload each extracted keyframe and collect the cloud URLs
+        image_urls = []
+        for image_path in image_paths:
+            cloud_url = upload_file(image_path)
+            image_urls.append({"image_url": cloud_url})
+
+        logger.info(f"Job {job_id}: Keyframes uploaded to cloud storage")
+
+        # Return the URLs of the uploaded keyframes
+        return {"image_urls": image_urls}, "/extract-keyframes", 200
+        
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error during keyframe extraction - {str(e)}")
+        return str(e), "/extract-keyframes", 500

routes/gdrive_upload.py

@@ -0,0 +1,265 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+import os
+import logging
+from flask import Blueprint, request, jsonify
+import threading
+import requests
+import uuid
+import json
+from google.oauth2.service_account import Credentials
+from google.auth.transport.requests import Request
+from datetime import datetime
+import time
+import psutil
+from services.authentication import authenticate
+from app_utils import validate_payload, queue_task_wrapper
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Define the blueprint
+gdrive_upload_bp = Blueprint('gdrive_upload', __name__)
+
+# Environment variables
+GCP_SA_CREDENTIALS = os.getenv('GCP_SA_CREDENTIALS')
+GDRIVE_USER = os.getenv('GDRIVE_USER')
+
+# Class to track upload progress
+class UploadProgress:
+    def __init__(self, job_id, total_size):
+        self.job_id = job_id
+        self.total_size = total_size
+        self.bytes_uploaded = 0
+        self.start_time = time.time()
+        self.lock = threading.Lock()
+        self.last_logged_percentage = 0
+        self.last_logged_resource_percentage = 0  # For memory/disk logging every 5%
+
+# Global list to keep track of active uploads
+active_uploads = []
+uploads_lock = threading.Lock()
+
+def get_access_token():
+    """
+    Retrieves an access token for Google APIs using service account credentials.
+    """
+    credentials_info = json.loads(GCP_SA_CREDENTIALS)
+    credentials = Credentials.from_service_account_info(
+        credentials_info,
+        scopes=['https://www.googleapis.com/auth/drive']
+    )
+    delegated_credentials = credentials.with_subject(GDRIVE_USER)
+    if not delegated_credentials.valid or delegated_credentials.expired:
+        delegated_credentials.refresh(Request())
+    access_token = delegated_credentials.token
+    return access_token
+
+def initiate_resumable_upload(filename, folder_id, mime_type='application/octet-stream'):
+    """
+    Initiates a resumable upload session with Google Drive and returns the upload URL.
+    """
+    url = 'https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable'
+    headers = {
+        'Authorization': f'Bearer {get_access_token()}',
+        'Content-Type': 'application/json; charset=UTF-8',
+        'X-Upload-Content-Type': mime_type
+    }
+    metadata = {
+        'name': filename,
+        'parents': [folder_id]
+    }
+    response = requests.post(url, headers=headers, data=json.dumps(metadata))
+    response.raise_for_status()
+    upload_url = response.headers['Location']
+    return upload_url
+
+def upload_file_in_chunks(file_url, upload_url, total_size, job_id, chunk_size):
+    """
+    Uploads the file to Google Drive in chunks by streaming data directly from the source URL.
+    """
+    bytes_uploaded = 0
+    max_retries = 5
+    retry_delay = 5  # seconds
+
+    progress = UploadProgress(job_id, total_size)
+
+    # Add progress to active_uploads
+    with uploads_lock:
+        active_uploads.append(progress)
+
+    try:
+        with requests.get(file_url, stream=True) as r:
+            r.raise_for_status()
+            iterator = r.iter_content(chunk_size=chunk_size)
+            for chunk in iterator:
+                if chunk:
+                    for attempt in range(max_retries):
+                        start = bytes_uploaded
+                        end = bytes_uploaded + len(chunk) - 1
+                        content_range = f'bytes {start}-{end}/{total_size}'
+                        headers = {
+                            'Content-Length': str(len(chunk)),
+                            'Content-Range': content_range,
+                        }
+                        try:
+                            upload_response = requests.put(
+                                upload_url,
+                                headers=headers,
+                                data=chunk
+                            )
+                            if upload_response.status_code in (200, 201):
+                                # Upload complete
+                                logger.info(f"Job {job_id}: Upload complete.")
+                                with progress.lock:
+                                    progress.bytes_uploaded = end + 1
+                                return upload_response.json()['id']
+                            elif upload_response.status_code == 308:
+                                # Resumable upload incomplete
+                                bytes_uploaded = end + 1
+                                with progress.lock:
+                                    progress.bytes_uploaded = bytes_uploaded
+                                break  # Break retry loop and continue with next chunk
+                            else:
+                                # Handle unexpected status codes
+                                logger.error(f"Job {job_id}: Unexpected status code: {upload_response.status_code}")
+                                raise Exception(f"Upload failed with status code {upload_response.status_code}")
+                        except requests.exceptions.RequestException as e:
+                            logger.error(f"Job {job_id}: Network error during upload: {e}")
+                            if attempt < max_retries - 1:
+                                logger.info(f"Job {job_id}: Retrying upload chunk after {retry_delay} seconds...")
+                                time.sleep(retry_delay)
+                                continue
+                            else:
+                                logger.error(f"Job {job_id}: Max retries reached. Upload failed.")
+                                raise
+                    else:
+                        # If we exhausted retries, exit the function
+                        raise Exception("Failed to upload chunk after multiple retries.")
+    finally:
+        # Remove progress from active_uploads
+        with uploads_lock:
+            if progress in active_uploads:
+                active_uploads.remove(progress)
+
+@gdrive_upload_bp.route('/gdrive-upload', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "file_url": {"type": "string", "format": "uri"},
+        "filename": {"type": "string"},
+        "folder_id": {"type": "string"},
+        "mime_type": {"type": "string"},
+        "chunk_size": {"type": "integer", "minimum": 1},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["file_url", "filename", "folder_id"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def gdrive_upload(job_id, data):
+    logger.info(f"Processing Job ID: {job_id}")
+
+    if not GDRIVE_USER:
+        logger.error("GDRIVE_USER environment variable is not set")
+        return "GDRIVE_USER environment variable is not set", "/gdrive-upload", 400
+
+    try:
+        file_url = data['file_url']
+        filename = data['filename']
+        folder_id = data['folder_id']
+        mime_type = data.get('mime_type', 'application/octet-stream')
+        chunk_size = data.get('chunk_size', 5 * 1024 * 1024)  # Default to 5 MB
+
+        # Get the total size of the file
+        try:
+            head_response = requests.head(file_url, allow_redirects=True, timeout=30)
+            head_response.raise_for_status()
+            total_size = int(head_response.headers.get('Content-Length', 0))
+            
+            get_response = requests.get(file_url, stream=True, timeout=30)
+            get_response.raise_for_status()
+            total_size = int(get_response.headers.get('Content-Length', 0))
+            if total_size == 0:
+                raise ValueError("Content-Length header is missing or zero")
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Job {job_id}: Error accessing file URL: {str(e)}")
+            return f"Error accessing file URL: {str(e)}", "/gdrive-upload", 500
+        except ValueError as e:
+            logger.error(f"Job {job_id}: {str(e)}")
+            return f"Unable to determine file size: {str(e)}", "/gdrive-upload", 500
+
+        logger.info(f"Job {job_id}: File size determined: {total_size} bytes")
+
+        # Initiate upload session
+        upload_url = initiate_resumable_upload(filename, folder_id, mime_type)
+        logger.info(f"Job {job_id}: Resumable upload session initiated with chunk size {chunk_size} bytes.")
+
+        # Upload file in chunks
+        file_id = upload_file_in_chunks(file_url, upload_url, total_size, job_id, chunk_size)
+
+        return file_id, "/gdrive-upload", 200
+
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error during processing - {str(e)}")
+        return str(e), "/gdrive-upload", 500
+
+def log_system_resources():
+    """
+    Logs system resource usage and upload progress at regular intervals.
+    """
+    while True:
+        # Get memory and disk usage
+        memory_info = psutil.virtual_memory()
+        disk_info = psutil.disk_usage('/')
+
+        with uploads_lock:
+            for progress in active_uploads:
+                with progress.lock:
+                    # Calculate the percentage uploaded
+                    percentage = (progress.bytes_uploaded / progress.total_size) * 100 if progress.total_size > 0 else 0
+                    elapsed_time = time.time() - progress.start_time
+
+                    # Log upload progress every 1%
+                    if int(percentage) >= progress.last_logged_percentage + 1:
+                        progress.last_logged_percentage = int(percentage)
+                        logger.info(
+                            f"Job {progress.job_id}: Uploaded {progress.bytes_uploaded} of {progress.total_size} bytes "
+                            f"({percentage:.2f}%), Elapsed Time: {int(elapsed_time)} seconds"
+                        )
+
+                    # Log system resource usage every 5%
+                    if int(percentage) >= progress.last_logged_resource_percentage + 5:
+                        progress.last_logged_resource_percentage = int(percentage)
+                        current_time = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+                        logger.info(f"[{current_time}] Memory Usage: {memory_info.percent}% used")
+                        logger.info(f"[{current_time}] Disk Usage: {disk_info.percent}% used")
+
+        # Sleep for 1 second before the next update
+        time.sleep(1)
+
+# Start the resource logging in a separate thread
+resource_logging_thread = threading.Thread(
+    target=log_system_resources,
+    daemon=True
+)
+resource_logging_thread.start()

routes/image_to_video.py

@@ -0,0 +1,72 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+from flask import Blueprint
+from app_utils import *
+import logging
+from services.image_to_video import process_image_to_video
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+
+image_to_video_bp = Blueprint('image_to_video', __name__)
+logger = logging.getLogger(__name__)
+
+@image_to_video_bp.route('/image-to-video', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "image_url": {"type": "string", "format": "uri"},
+        "length": {"type": "number", "minimum": 1, "maximum": 60},
+        "frame_rate": {"type": "integer", "minimum": 15, "maximum": 60},
+        "zoom_speed": {"type": "number", "minimum": 0, "maximum": 100},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["image_url"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def image_to_video(job_id, data):
+    image_url = data.get('image_url')
+    length = data.get('length', 5)
+    frame_rate = data.get('frame_rate', 30)
+    zoom_speed = data.get('zoom_speed', 3) / 100
+    webhook_url = data.get('webhook_url')
+    id = data.get('id')
+
+    logger.info(f"Job {job_id}: Received image to video request for {image_url}")
+
+    try:
+        # Process image to video conversion
+        output_filename = process_image_to_video(
+            image_url, length, frame_rate, zoom_speed, job_id, webhook_url
+        )
+
+        # Upload the resulting file using the unified upload_file() method
+        cloud_url = upload_file(output_filename)
+
+        # Log the successful upload
+        logger.info(f"Job {job_id}: Converted video uploaded to cloud storage: {cloud_url}")
+
+        # Return the cloud URL for the uploaded file
+        return cloud_url, "/image-to-video", 200
+        
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error processing image to video: {str(e)}", exc_info=True)
+        return str(e), "/image-to-video", 500

routes/media_to_mp3.py

@@ -0,0 +1,64 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+# routes/media_to_mp3.py
+from flask import Blueprint, current_app
+from app_utils import *
+import logging
+from services.ffmpeg_toolkit import process_conversion
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+import os
+
+convert_bp = Blueprint('convert', __name__)
+logger = logging.getLogger(__name__)
+
+@convert_bp.route('/media-to-mp3', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "media_url": {"type": "string", "format": "uri"},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"},
+        "bitrate": {"type": "string", "pattern": "^[0-9]+k$"}
+    },
+    "required": ["media_url"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def convert_media_to_mp3(job_id, data):
+    media_url = data['media_url']
+    webhook_url = data.get('webhook_url')
+    id = data.get('id')
+    bitrate = data.get('bitrate', '128k')
+
+    logger.info(f"Job {job_id}: Received media-to-mp3 request for media URL: {media_url}")
+
+    try:
+        output_file = process_conversion(media_url, job_id, bitrate)
+        logger.info(f"Job {job_id}: Media conversion process completed successfully")
+
+        cloud_url = upload_file(output_file)
+        logger.info(f"Job {job_id}: Converted media uploaded to cloud storage: {cloud_url}")
+
+        return cloud_url, "/media-to-mp3", 200
+
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error during media conversion process - {str(e)}")
+        return str(e), "/media-to-mp3", 500

routes/transcribe_media.py

@@ -0,0 +1,68 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+from flask import Blueprint
+from app_utils import *
+import logging
+import os
+from services.transcription import process_transcription
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+
+transcribe_bp = Blueprint('transcribe', __name__)
+logger = logging.getLogger(__name__)
+
+@transcribe_bp.route('/transcribe-media', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "media_url": {"type": "string", "format": "uri"},
+        "output": {"type": "string", "enum": ["transcript", "srt", "vtt", "ass"]},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "max_chars": {"type": "integer"},
+        "id": {"type": "string"}
+    },
+    "required": ["media_url"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def transcribe(job_id, data):
+    media_url = data['media_url']
+    output = data.get('output', 'transcript')
+    webhook_url = data.get('webhook_url')
+    max_chars = data.get('max_chars', 56)
+    id = data.get('id')
+
+    logger.info(f"Job {job_id}: Received transcription request for {media_url}")
+
+    try:
+        result = process_transcription(media_url, output, max_chars)
+        logger.info(f"Job {job_id}: Transcription process completed successfully")
+
+        # If the result is a file path, upload it using the unified upload_file() method
+        if output in ['srt', 'vtt', 'ass']:
+            cloud_url = upload_file(result)
+            os.remove(result)  # Remove the temporary file after uploading
+            return cloud_url, "/transcribe-media", 200
+        else:
+            return result, "/transcribe-media", 200
+        
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error during transcription process - {str(e)}")
+        return str(e), "/transcribe-media", 500

routes/v1/audio/concatenate.py

@@ -0,0 +1,57 @@
+from flask import Blueprint
+from app_utils import *
+import logging
+from services.v1.audio.concatenate import process_audio_concatenate
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+
+v1_audio_concatenate_bp = Blueprint("v1_audio_concatenate", __name__)
+logger = logging.getLogger(__name__)
+
+
+@v1_audio_concatenate_bp.route("/v1/audio/concatenate", methods=["POST"])
+@authenticate
+@validate_payload(
+    {
+        "type": "object",
+        "properties": {
+            "audio_urls": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {"audio_url": {"type": "string", "format": "uri"}},
+                    "required": ["audio_url"],
+                },
+                "minItems": 1,
+            },
+            "webhook_url": {"type": "string", "format": "uri"},
+            "id": {"type": "string"},
+        },
+        "required": ["audio_urls"],
+        "additionalProperties": False,
+    }
+)
+@queue_task_wrapper(bypass_queue=False)
+def combine_audio(job_id, data):
+    media_urls = data["audio_urls"]
+    webhook_url = data.get("webhook_url")
+    id = data.get("id")
+
+    logger.info(
+        f"Job {job_id}: Received combine-audio request for {len(media_urls)} audio files"
+    )
+
+    try:
+        output_file = process_audio_concatenate(media_urls, job_id)
+        logger.info(f"Job {job_id}: Audio combination process completed successfully")
+
+        cloud_url = upload_file(output_file)
+        logger.info(
+            f"Job {job_id}: Combined audio uploaded to cloud storage: {cloud_url}"
+        )
+
+        return cloud_url, "/v1/audio/concatenate", 200
+
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error during audio combination process - {str(e)}")
+        return str(e), "/v1/audio/concatenate", 500

routes/v1/code/execute/execute_python.py

@@ -0,0 +1,140 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+import os
+import logging
+from flask import Blueprint, request
+from services.authentication import authenticate
+from app_utils import validate_payload, queue_task_wrapper
+import subprocess
+import tempfile
+import json
+import textwrap
+
+v1_code_execute_bp = Blueprint('v1_code_execute', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_code_execute_bp.route('/v1/code/execute/python', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "code": {"type": "string"},
+        "timeout": {"type": "integer", "minimum": 1, "maximum": 300},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["code"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def execute_python(job_id, data):
+    logger.info(f"Job {job_id}: Received Python code execution request")
+    
+    try:
+        code = data['code']
+        timeout = data.get('timeout', 30)
+        
+        # Indent user code
+        indented_code = textwrap.indent(code, '    ')
+        
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as temp_file:
+            template = '''import sys
+import json
+from io import StringIO
+import contextlib
+
+@contextlib.contextmanager
+def capture_output():
+    stdout, stderr = StringIO(), StringIO()
+    old_out, old_err = sys.stdout, sys.stderr
+    try:
+        sys.stdout, sys.stderr = stdout, stderr
+        yield stdout, stderr
+    finally:
+        sys.stdout, sys.stderr = old_out, old_err
+
+def execute_code():
+{}
+
+with capture_output() as (stdout, stderr):
+    try:
+        result_value = execute_code()
+    except Exception as e:
+        print(f"Error: {{str(e)}}", file=sys.stderr)
+        result_value = None
+
+result = {{
+    'stdout': stdout.getvalue(),
+    'stderr': stderr.getvalue(),
+    'return_value': result_value
+}}
+print(json.dumps(result))
+'''
+            
+            final_code = template.format(indented_code)
+            temp_file.write(final_code)
+            temp_file.flush()
+            
+            # Log the generated code for debugging
+            logger.debug(f"Generated code:\n{final_code}")
+            
+            try:
+                result = subprocess.run(
+                    ['python3', temp_file.name],
+                    capture_output=True,
+                    text=True,
+                    timeout=timeout
+                )
+                
+                try:
+                    output = json.loads(result.stdout)
+                    if result.returncode != 0 or output['stderr']:
+                        return {
+                            'error': output['stderr'] or 'Execution failed',
+                            'stdout': output['stdout'],
+                            'exit_code': result.returncode
+                        }, '/v1/code/execute/python', 400
+                    
+                    return {
+                        'result': output['return_value'],
+                        'stdout': output['stdout'],
+                        'stderr': output['stderr'],
+                        'exit_code': result.returncode
+                    }, '/v1/code/execute/python', 200
+                    
+                except json.JSONDecodeError:
+                    return {
+                        'error': 'Failed to parse execution result',
+                        'stdout': result.stdout,
+                        'stderr': result.stderr,
+                        'exit_code': result.returncode
+                    }, '/v1/code/execute/python', 500
+                    
+            except subprocess.TimeoutExpired:
+                return {"error": f"Execution timed out after {timeout} seconds"}, '/v1/code/execute/python', 408
+            except subprocess.SubprocessError as e:
+                return {"error": f"Execution failed: {str(e)}"}, '/v1/code/execute/python', 500
+            
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error executing Python code: {str(e)}")
+        return {"error": str(e)}, '/v1/code/execute/python', 500
+        
+    finally:
+        if 'temp_file' in locals():
+            os.unlink(temp_file.name)

routes/v1/ffmpeg/ffmpeg_compose.py

@@ -0,0 +1,149 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+import os
+import logging
+from flask import Blueprint, request, jsonify
+from app_utils import *
+from services.v1.ffmpeg.ffmpeg_compose import process_ffmpeg_compose
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+
+v1_ffmpeg_compose_bp = Blueprint('v1_ffmpeg_compose', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_ffmpeg_compose_bp.route('/v1/ffmpeg/compose', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "inputs": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "file_url": {"type": "string", "format": "uri"},
+                    "options": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "option": {"type": "string"},
+                                "argument": {"type": ["string", "number", "null"]}
+                            },
+                            "required": ["option"]
+                        }
+                    }
+                },
+                "required": ["file_url"]
+            },
+            "minItems": 1
+        },
+        "filters": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "filter": {"type": "string"}
+                },
+                "required": ["filter"]
+            }
+        },
+        "outputs": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "options": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "option": {"type": "string"},
+                                "argument": {"type": ["string", "number", "null"]}
+                            },
+                            "required": ["option"]
+                        }
+                    }
+                },
+                "required": ["options"]
+            },
+            "minItems": 1
+        },
+        "global_options": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "option": {"type": "string"},
+                    "argument": {"type": ["string", "number", "null"]}
+                },
+                "required": ["option"]
+            }
+        },
+        "metadata": {
+            "type": "object",
+            "properties": {
+                "thumbnail": {"type": "boolean"},
+                "filesize": {"type": "boolean"},
+                "duration": {"type": "boolean"},
+                "bitrate": {"type": "boolean"},
+                "encoder": {"type": "boolean"}
+            }
+        },
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["inputs", "outputs"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def ffmpeg_api(job_id, data):
+    logger.info(f"Job {job_id}: Received flexible FFmpeg request")
+
+    try:
+        output_filenames, metadata = process_ffmpeg_compose(data, job_id)
+        
+        # Upload output files to GCP and create result array
+        output_urls = []
+        for i, output_filename in enumerate(output_filenames):
+            if os.path.exists(output_filename):
+                upload_url = upload_file(output_filename)
+                output_info = {"file_url": upload_url}
+                
+                if metadata and i < len(metadata):
+                    output_metadata = metadata[i]
+                    if 'thumbnail' in output_metadata:
+                        thumbnail_path = output_metadata['thumbnail']
+                        if os.path.exists(thumbnail_path):
+                            thumbnail_url = upload_file(thumbnail_path)
+                            del output_metadata['thumbnail']
+                            output_metadata['thumbnail_url'] = thumbnail_url
+                            os.remove(thumbnail_path)  # Clean up local thumbnail file
+                    output_info.update(output_metadata)
+                
+                output_urls.append(output_info)
+                os.remove(output_filename)  # Clean up local output file after upload
+            else:
+                raise Exception(f"Expected output file {output_filename} not found")
+
+        return output_urls, "/v1/ffmpeg/compose", 200
+        
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error processing FFmpeg request - {str(e)}")
+        return str(e), "/v1/ffmpeg/compose", 500

routes/v1/image/convert/image_to_video.py

@@ -0,0 +1,73 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+from flask import Blueprint
+from app_utils import *
+import logging
+from services.v1.image.convert.image_to_video import process_image_to_video
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+
+v1_image_convert_video_bp = Blueprint('v1_image_convert_video', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_image_convert_video_bp.route('/v1/image/convert/video', methods=['POST'])
+@v1_image_convert_video_bp.route('/v1/image/transform/video', methods=['POST']) #depleft for backwards compatibility, do not use.
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "image_url": {"type": "string", "format": "uri"},
+        "length": {"type": "number", "minimum": 0.1, "maximum": 400},
+        "frame_rate": {"type": "integer", "minimum": 15, "maximum": 60},
+        "zoom_speed": {"type": "number", "minimum": 0, "maximum": 100},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["image_url"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def image_to_video(job_id, data):
+    image_url = data.get('image_url')
+    length = data.get('length', 5)
+    frame_rate = data.get('frame_rate', 30)
+    zoom_speed = data.get('zoom_speed', 3) / 100
+    webhook_url = data.get('webhook_url')
+    id = data.get('id')
+
+    logger.info(f"Job {job_id}: Received image to video request for {image_url}")
+
+    try:
+        # Process image to video conversion
+        output_filename = process_image_to_video(
+            image_url, length, frame_rate, zoom_speed, job_id, webhook_url
+        )
+
+        # Upload the resulting file using the unified upload_file() method
+        cloud_url = upload_file(output_filename)
+
+        # Log the successful upload
+        logger.info(f"Job {job_id}: Converted video uploaded to cloud storage: {cloud_url}")
+
+        # Return the cloud URL for the uploaded file
+        return cloud_url, "/v1/image/convert/video", 200
+        
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error processing image to video: {str(e)}", exc_info=True)
+        return str(e), "/v1/image/convert/video", 500

routes/v1/image/screenshot_webpage.py

@@ -0,0 +1,125 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+# Author: Harrison Fisher (https://github.com/HarrisonFisher)
+# Date: April 2025
+# Created new route: /v1/playwright/screenshot
+
+from flask import Blueprint, request, jsonify
+from app_utils import *
+from app_utils import validate_payload, queue_task_wrapper
+import logging
+import os
+from services.v1.image.screenshot_webpage import take_screenshot
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+from playwright.sync_api import sync_playwright
+from io import BytesIO
+
+
+v1_image_screenshot_webpage_bp = Blueprint('v1_image_screenshot_webpage', __name__)
+logger = logging.getLogger(__name__)
+
+
+@v1_image_screenshot_webpage_bp.route('/v1/image/screenshot/webpage', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "url": {"type": "string", "format": "uri"},
+        "html": {"type": "string"},
+        "viewport_width": {"type": "integer", "minimum": 1},
+        "viewport_height": {"type": "integer", "minimum": 1},
+        "full_page": {"type": "boolean", "default": False},
+        "format": {"type": "string", "enum": ["png", "jpeg"], "default": "png"},
+        "delay": {"type": "integer", "minimum": 0},
+        "device_scale_factor": {"type": "number", "minimum": 0.1},
+        "user_agent": {"type": "string"},
+        "cookies": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["name", "value", "domain"],
+                "properties": {
+                    "name": {"type": "string"},
+                    "value": {"type": "string"},
+                    "domain": {"type": "string"},
+                    "path": {"type": "string", "default": "/"},
+                },
+                "additionalProperties": True
+            }
+        },
+        "headers": {
+            "type": "object",
+            "additionalProperties": {"type": "string"}
+        },
+        "quality": {"type": "integer", "minimum": 0, "maximum": 100},
+        "clip": {
+            "type": "object",
+            "required": ["x", "y", "width", "height"],
+            "properties": {
+                "x": {"type": "number"},
+                "y": {"type": "number"},
+                "width": {"type": "number", "exclusiveMinimum": 0},
+                "height": {"type": "number", "exclusiveMinimum": 0}
+            }
+        },
+        "timeout": {"type": "integer", "minimum": 100},
+        "wait_until": {"type": "string", "enum": ["load", "domcontentloaded", "networkidle", "networkidle2"], "default": "load"},
+        "wait_for_selector": {"type": "string"},
+        "emulate": {
+            "type": "object",
+            "properties": {
+                "color_scheme": {
+                    "type": "string",
+                    "enum": ["light", "dark"]
+                }
+            }
+        },
+        "omit_background": {"type": "boolean", "default": False},
+        "selector": {"type": "string"},
+        "js": {"type": "string"},
+        "css": {"type": "string"},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "oneOf": [
+        {"required": ["url"]},
+        {"required": ["html"]}
+    ],
+    "not": {"required": ["url", "html"]},
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def screenshot(job_id, data):
+    logger.info(f"Job {job_id}: Received screenshot request for {data.get('url')}")
+    try:
+        screenshot_io = take_screenshot(data, job_id)
+        if isinstance(screenshot_io, dict) and 'error' in screenshot_io:
+            logger.error(f"Job {job_id}: Screenshot error: {screenshot_io['error']}")
+            return {"error": screenshot_io['error']}, "/v1/image/screenshot/webpage", 400
+        format = data.get("format", "png")
+        temp_file_path = f"{job_id}_screenshot.{format}"
+        with open(temp_file_path, "wb") as temp_file:
+            temp_file.write(screenshot_io.read())
+        cloud_url = upload_file(temp_file_path)
+        os.remove(temp_file_path)
+        logger.info(f"Job {job_id}: Screenshot successfully processed and uploaded.")
+        return cloud_url, "/v1/image/screenshot/webpage", 200
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error processing screenshot: {str(e)}", exc_info=True)
+        return {"error": str(e)}, "/v1/image/screenshot/webpage", 500

routes/v1/media/convert/media_convert.py

@@ -0,0 +1,81 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+from flask import Blueprint, jsonify
+from app_utils import validate_payload, queue_task_wrapper
+import logging
+from services.v1.media.convert.media_convert import process_media_convert
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+import os
+
+v1_media_convert_bp = Blueprint('v1_media_convert', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_media_convert_bp.route('/v1/media/convert', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "media_url": {"type": "string", "format": "uri"},
+        "format": {"type": "string"},
+        "video_codec": {"type": "string"},
+        "video_preset": {"type": "string"},
+        "video_crf": {"type": "number", "minimum": 0, "maximum": 51},
+        "audio_codec": {"type": "string"},
+        "audio_bitrate": {"type": "string"},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"}
+    },
+    "required": ["media_url", "format"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def convert_media_format(job_id, data):
+    media_url = data['media_url']
+    output_format = data['format']
+    video_codec = data.get('video_codec', 'libx264')
+    video_preset = data.get('video_preset', 'medium')
+    video_crf = data.get('video_crf', 23)
+    audio_codec = data.get('audio_codec', 'aac')
+    audio_bitrate = data.get('audio_bitrate', '128k')
+    webhook_url = data.get('webhook_url')
+    id = data.get('id')
+
+    logger.info(f"Job {job_id}: Received media conversion request for media URL: {media_url} to format: {output_format}")
+
+    try:
+        output_file = process_media_convert(
+            media_url, 
+            job_id, 
+            output_format, 
+            video_codec, 
+            video_preset,
+            video_crf,
+            audio_codec,
+            audio_bitrate,
+            webhook_url
+        )
+        logger.info(f"Job {job_id}: Media format conversion completed successfully")
+
+        cloud_url = upload_file(output_file)
+        logger.info(f"Job {job_id}: Converted media uploaded to cloud storage: {cloud_url}")
+        
+        return cloud_url, "/v1/media/convert", 200
+
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error during media conversion process - {str(e)}")
+        return {"error": str(e)}, "/v1/media/convert", 500 

routes/v1/media/convert/media_to_mp3.py

@@ -0,0 +1,67 @@
+# Copyright (c) 2025 Stephen G. Pope
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+
+
+# routes/media_to_mp3.py
+from flask import Blueprint, current_app
+from app_utils import *
+import logging
+from services.v1.media.convert.media_to_mp3 import process_media_to_mp3
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+import os
+
+v1_media_convert_mp3_bp = Blueprint('v1_media_convert_mp3', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_media_convert_mp3_bp.route('/v1/media/convert/mp3', methods=['POST'])
+@v1_media_convert_mp3_bp.route('/v1/media/transform/mp3', methods=['POST']) #depleft for backwards compatibility, do not use.
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "media_url": {"type": "string", "format": "uri"},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"},
+        "bitrate": {"type": "string", "pattern": "^[0-9]+k$"},
+        "sample_rate": {"type": "number"}
+    },
+    "required": ["media_url"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def convert_media_to_mp3(job_id, data):
+    media_url = data['media_url']
+    webhook_url = data.get('webhook_url')
+    id = data.get('id')
+    bitrate = data.get('bitrate', '128k')
+    sample_rate = data.get('sample_rate')
+
+    logger.info(f"Job {job_id}: Received media-to-mp3 request for media URL: {media_url}")
+
+    try:
+        output_file = process_media_to_mp3(media_url, job_id, bitrate, sample_rate)
+        logger.info(f"Job {job_id}: Media conversion process completed successfully")
+
+        cloud_url = upload_file(output_file)
+        logger.info(f"Job {job_id}: Converted media uploaded to cloud storage: {cloud_url}")
+
+        return cloud_url, "/v1/media/transform/mp3", 200
+
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error during media conversion process - {str(e)}")
+        return str(e), "/v1/media/transform/mp3", 500

routes/v1/media/download.py

@@ -0,0 +1,230 @@
+from flask import Blueprint
+from app_utils import *
+import logging
+import os
+import yt_dlp
+import tempfile
+from werkzeug.utils import secure_filename
+import uuid
+from services.cloud_storage import upload_file
+from services.authentication import authenticate
+from services.file_management import download_file
+from urllib.parse import quote, urlparse
+
+v1_media_download_bp = Blueprint('v1_media_download', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_media_download_bp.route('/v1/BETA/media/download', methods=['POST'])
+@authenticate
+@validate_payload({
+    "type": "object",
+    "properties": {
+        "media_url": {"type": "string", "format": "uri"},
+        "webhook_url": {"type": "string", "format": "uri"},
+        "id": {"type": "string"},
+        "cookie": {"type": "string", "description": "Path to cookie file, URL to cookie file, or cookie string in Netscape format"},
+        "cloud_upload": {"type": "boolean"},
+        "format": {
+            "type": "object",
+            "properties": {
+                "quality": {"type": "string"},
+                "format_id": {"type": "string"},
+                "resolution": {"type": "string"},
+                "video_codec": {"type": "string"},
+                "audio_codec": {"type": "string"}
+            }
+        },
+        "audio": {
+            "type": "object",
+            "properties": {
+                "extract": {"type": "boolean"},
+                "format": {"type": "string"},
+                "quality": {"type": "string"}
+            }
+        },
+        "thumbnails": {
+            "type": "object",
+            "properties": {
+                "download": {"type": "boolean"},
+                "download_all": {"type": "boolean"},
+                "formats": {"type": "array", "items": {"type": "string"}},
+                "convert": {"type": "boolean"},
+                "embed_in_audio": {"type": "boolean"}
+            }
+        },
+        "subtitles": {
+            "type": "object",
+            "properties": {
+                "download": {"type": "boolean"},
+                "languages": {"type": "array", "items": {"type": "string"}},
+                "formats": {"type": "array", "items": {"type": "string"}}
+            }
+        },
+        "download": {
+            "type": "object",
+            "properties": {
+                "max_filesize": {"type": "integer"},
+                "rate_limit": {"type": "string"},
+                "retries": {"type": "integer"}
+            }
+        }
+    },
+    "required": ["media_url"],
+    "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def download_media(job_id, data):
+    media_url = data['media_url']
+    cookie = data.get('cookie')
+
+    format_options = data.get('format', {})
+    audio_options = data.get('audio', {})
+    thumbnail_options = data.get('thumbnails', {})
+    subtitle_options = data.get('subtitles', {})
+    download_options = data.get('download', {})
+
+    logger.info(f"Job {job_id}: Received download request for {media_url}")
+
+    try:
+        # Create a temporary directory for downloads
+        with tempfile.TemporaryDirectory() as temp_dir:
+            # Configure yt-dlp options
+            ydl_opts = {
+                'format': 'best',  # Download best quality
+                'outtmpl': os.path.join(temp_dir, '%(title)s.%(ext)s'),
+                'quiet': True,
+                'no_warnings': True,
+                'download': data.get('cloud_upload', True)
+            }
+
+            # Add cookies if provided
+            if cookie:
+                if os.path.isfile(cookie):
+                    ydl_opts['cookiefile'] = cookie
+                elif urlparse(cookie).scheme in ('http', 'https'):
+                    # If cookie is a URL, download it first
+                    ydl_opts['cookiefile'] = download_file(cookie, temp_dir)
+                else:
+                    # If cookie is a string, write it to a temporary file
+                    cookie_file = os.path.join(temp_dir, 'cookies.txt')
+                    with open(cookie_file, 'w') as f:
+                        f.write(cookie)
+                    ydl_opts['cookiefile'] = cookie_file
+
+            # Add format options if specified
+            if format_options:
+                format_str = []
+                if format_options.get('quality'):
+                    format_str.append(format_options['quality'])
+                if format_options.get('format_id'):
+                    format_str.append(format_options['format_id'])
+                if format_options.get('resolution'):
+                    format_str.append(format_options['resolution'])
+                if format_options.get('video_codec'):
+                    format_str.append(format_options['video_codec'])
+                if format_options.get('audio_codec'):
+                    format_str.append(format_options['audio_codec'])
+                if format_str:
+                    ydl_opts['format'] = '+'.join(format_str)
+
+            # Add audio options if specified
+            if audio_options:
+                if audio_options.get('extract'):
+                    ydl_opts['extract_audio'] = True
+                    if audio_options.get('format'):
+                        ydl_opts['audio_format'] = audio_options['format']
+                    if audio_options.get('quality'):
+                        ydl_opts['audio_quality'] = audio_options['quality']
+
+            # Add thumbnail options if specified
+            if thumbnail_options:
+                ydl_opts['writesubtitles'] = thumbnail_options.get('download', False)
+                ydl_opts['writeallsubtitles'] = thumbnail_options.get('download_all', False)
+                if thumbnail_options.get('formats'):
+                    ydl_opts['subtitleslangs'] = thumbnail_options['formats']
+                ydl_opts['convert_thumbnails'] = thumbnail_options.get('convert', False)
+                ydl_opts['embed_thumbnail_in_audio'] = thumbnail_options.get('embed_in_audio', False)
+
+            # Add subtitle options if specified
+            if subtitle_options:
+                ydl_opts['writesubtitles'] = subtitle_options.get('download', False)
+                if subtitle_options.get('languages'):
+                    ydl_opts['subtitleslangs'] = subtitle_options['languages']
+                if subtitle_options.get('formats'):
+                    ydl_opts['subtitlesformat'] = subtitle_options['formats']
+
+            # Add download options if specified
+            if download_options:
+                if download_options.get('max_filesize'):
+                    ydl_opts['max_filesize'] = download_options['max_filesize']
+                if download_options.get('rate_limit'):
+                    ydl_opts['limit_rate'] = download_options['rate_limit']
+                if download_options.get('retries'):
+                    ydl_opts['retries'] = download_options['retries']
+
+            # Download the media
+            with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+                info = ydl.extract_info(media_url, download=data.get('cloud_upload', True))
+                
+                if not data.get('cloud_upload', True):
+                    media_url = info['url']
+                else:
+                    filename = ydl.prepare_filename(info)
+                    # Upload to cloud storage
+                    media_url = upload_file(filename)
+                    # Clean up the temporary file
+                    os.remove(filename)
+
+                # Prepare response
+                response = {
+                    "media": {
+                        "media_url": media_url,
+                        "title": info.get('title'),
+                        "format_id": info.get('format_id'),
+                        "ext": info.get('ext'),
+                        "resolution": info.get('resolution'),
+                        "filesize": info.get('filesize'),
+                        "width": info.get('width'),
+                        "height": info.get('height'),
+                        "fps": info.get('fps'),
+                        "video_codec": info.get('vcodec'),
+                        "audio_codec": info.get('acodec'),
+                        "upload_date": info.get('upload_date'),
+                        "duration": info.get('duration'),
+                        "view_count": info.get('view_count'),
+                        "uploader": info.get('uploader'),
+                        "uploader_id": info.get('uploader_id'),
+                        "description": info.get('description')
+                    }
+                }
+
+                # Add thumbnails if available and requested
+                if info.get('thumbnails') and thumbnail_options.get('download', False):
+                    response["thumbnails"] = []
+                    for thumbnail in info['thumbnails']:
+                        if thumbnail.get('url'):
+                            try:
+                                # Download the thumbnail first
+                                thumbnail_path = download_file(thumbnail['url'], temp_dir)
+                                # Upload to cloud storage
+                                thumbnail_url = upload_file(thumbnail_path)
+                                # Clean up the temporary thumbnail file
+                                os.remove(thumbnail_path)
+                                
+                                response["thumbnails"].append({
+                                    "id": thumbnail.get('id', 'default'),
+                                    "image_url": thumbnail_url,
+                                    "width": thumbnail.get('width'),
+                                    "height": thumbnail.get('height'),
+                                    "original_format": thumbnail.get('ext'),
+                                    "converted": thumbnail.get('converted', False)
+                                })
+                            except Exception as e:
+                                logger.error(f"Error processing thumbnail: {str(e)}")
+                                continue
+                
+                return response, "/v1/media/download", 200
+
+    except Exception as e:
+        logger.error(f"Job {job_id}: Error during download process - {str(e)}")
+        return str(e), "/v1/media/download", 500