diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000000000000000000000000000000000000..83868b797f9f58f2102bde6136cf448b444b6fb4
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,25 @@
+# Ignore Python cache and compiled files
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Ignore environment and config files
+.env
+.env_variables.json
+.env_shell.json
+
+# Ignore version control and editor files
+.git/
+.vscode/
+.DS_Store
+
+# Ignore scripts and documentation not needed in image
+README.md
+local.sh
+generate_vector.sh
+docs/
+
+# Ignore repository/configuration files not needed in image
+.github/
+.gitignore
diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000000000000000000000000000000000000..2f0344fce670756f2d49717f421e6afbafb6024d
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,49 @@
+# Production Environment Configuration
+# No Code Architect Toolkit
+
+# 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=1993
+
+# 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
\ No newline at end of file
diff --git a/.env.local.minio.n8n.example b/.env.local.minio.n8n.example
new file mode 100644
index 0000000000000000000000000000000000000000..03444092ebf14c95ce966738a9eb321bd7878318
--- /dev/null
+++ b/.env.local.minio.n8n.example
@@ -0,0 +1,29 @@
+# Local Development Environment Configuration
+# No Code Architect Toolkit - Local Setup with MinIO
+
+# App Configuration
+APP_NAME=NCAToolkit
+APP_DEBUG=true
+APP_DOMAIN=localhost:8080
+APP_URL=http://localhost:8080
+
+# API Configuration
+API_KEY=local-dev-key-123
+
+# MinIO S3-Compatible Storage Configuration
+S3_ENDPOINT_URL=http://minio:9000
+S3_ACCESS_KEY=minioadmin
+S3_SECRET_KEY=minioadmin123
+S3_REGION=us-east-1
+S3_BUCKET_NAME=nca-toolkit-local
+
+# Optional: Gunicorn Configuration
+GUNICORN_WORKERS=2
+GUNICORN_TIMEOUT=300
+
+# n8n Configuration
+N8N_HOST=localhost
+N8N_PORT=5678
+N8N_PROTOCOL=http
+WEBHOOK_URL=http://localhost:5678/
+GENERIC_TIMEZONE=UTC
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000000000000000000000000000000000000..efc67839875605b9f1b6f8a7d6bff76cf92f6b77
--- /dev/null
+++ b/.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.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000000000000000000000000000000000000..279a097a60559c8bc89cbf1827e2d996eaf6848e
--- /dev/null
+++ b/.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?
\ No newline at end of file
diff --git a/.github/workflows/update-build-number.yml b/.github/workflows/update-build-number.yml
new file mode 100644
index 0000000000000000000000000000000000000000..d3367cdd289b2aed91359338b5c9c62a9c5ea87e
--- /dev/null
+++ b/.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
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000000000000000000000000000000000000..bbb0886608dc9bfdc060837142f947e02830fb6a
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+.env_variables.json
+.DS_Store
+.env_shell.json
+.env
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000000000000000000000000000000000000..dfab3b524729165a806ca9d4ebfcb0cd9126502f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,158 @@
+# Contributing to No-Code Architects Toolkit
+
+Thanks for your interest in contributing! ❤️
+
+This project exists to help **non-technical creators build smarter systems** — so every contribution should align with these core principles:
+
+✅ Simple
+✅ Useful
+✅ Low-maintenance
+
+This repository is focused on new contributions and feature development. Please ensure all pull requests contain complete, debugged code that is ready for review. We do not accept submissions that require significant cleanup, completion work, or debugging by maintainers.
+
+> If you like the project but don't know how to code, you can still support us in other ways:
+>
+> * ⭐ Star the project
+> * 📣 Share it on social media
+> * 🌲 Refer it to a friend or your community
+> * 💸 [Sponsor the project](#)
+
+If you need help or have questions, check out the GitHub [discussions](https://github.com/stephengpope/no-code-architects-toolkit/discussions) or join the [community](https://www.skool.com/no-code-architects/about?ref=2f302c52a77541efa2dd5e8b27f3f8c9).
+
+---
+
+## Table of Contents
+
+* [What We Accept](#what-we-accept-)
+* [What We Reject](#what-we-reject-)
+* [Feature Evaluation Framework](#feature-evaluation-framework)
+* [Technical Guidelines](#technical-guidelines)
+* [Contribution Types](#contribution-types)
+* [Branch Naming Conventions](#branch-naming-conventions)
+* [Final Thoughts](#final-thoughts-%EF%B8%8F)
+
+---
+
+## What We Accept ✅
+
+* Solves **common no-code challenges**
+* **Reduces cost** or replaces paid APIs/tools
+* Requires minimal input (has defaults)
+* Is understandable by **non-technical users**
+* Works out-of-the-box, no setup required
+* One-time integrations — **no constant maintenance needed**
+* Uses **existing input/output naming conventions**
+* Follows our directory and structure conventions
+
+---
+
+## What We Reject ❌
+
+* Features built for one person or edge-case
+* Inconsistent input/output field names
+* Requires polling, retries, or callback logic
+* Needs babysitting or breaks frequently
+* Lacks error handling or code comments
+* Includes unused code, requirements, or bloat
+* Adds huge packages that inflate Docker image size
+* Leaves us with more work to do
+
+---
+
+## Feature Evaluation Framework
+
+| Category | Ask This... | ✅ Accept if... | ❌ Reject if... |
+| --------------------- | ---------------------------------------------- | ---------------------------------------------- | ------------------------------------------ |
+| **Mission Fit** | Does this reduce cost or unify tools? | Replaces APIs, reduces costs or complexity | Adds noise or solves narrow edge cases |
+| **Input Familiarity** | Are inputs familiar (`file_url`, `text`, etc)? | Uses standard names/types already in use | Introduces new terms for same ideas |
+| **Input Clarity** | Would a non-tech user know what to enter? | Inputs like "Enter URL", "Choose format" | Needs tech explanation or experimentation |
+| **Output Usefulness** | Can this plug straight into Make/Zapier? | Returns clean files, text, URLs | Returns raw data or deep nested structures |
+| **Reliability** | Will it just work? | API is stable, no retries, consistent behavior | Depends on flaky APIs or fragile setup |
+| **Maintenance Cost** | Will we have to maintain this? | One-and-done, doesn't change often | Vendor changes often, breaks silently |
+| **Value vs. Effort** | Is it worth it? | High impact, frequently requested | Niche, low ROI |
+
+---
+
+## Technical Guidelines
+
+> These guidelines help maintain a clean and production-ready project.
+
+### 🧠 Code Style
+
+* Use **clear, descriptive names** (e.g., `convertImageToText`, not `imgTxt`)
+* Comment your logic if it's not obvious
+* Handle errors — don't let code crash silently
+* Follow consistent formatting
+
+
+### 🧼 Clean Contributions
+
+* Don't change files unrelated to your feature
+* Don't leave behind unused requirements or code
+* Don't introduce huge dependencies (we check image size)
+* Use `git status` to review your working tree before you commit
+---
+
+## Branch Naming Conventions
+
+All contributions should follow this process:
+
+1. Fork the [main repository](https://github.com/stephengpope/no-code-architects-toolkit)
+2. Clone your fork:
+ ```bash
+ git clone https://github.com/YOUR_USERNAME/no-code-architects-toolkit.git
+ cd no-code-architects-toolkit
+ ```
+3. Add the upstream repository:
+ ```bash
+ git remote add upstream https://github.com/stephengpope/no-code-architects-toolkit.git
+ ```
+4. Fetch and checkout the upstream build branch:
+ ```bash
+ git fetch upstream
+ git checkout -b your-feature-branch upstream/build
+ ```
+5. Name your feature branch following these patterns:
+ * For bug fixes: `fix/descriptive-bug-name`
+ * For new features: `feature/descriptive-feature-name`
+ * For documentation: `docs/descriptive-change`
+
+Example:
+```bash
+# For a new feature
+git fetch upstream
+git checkout -b feature/pdf-to-text-converter upstream/build
+
+# For a bug fix
+git fetch upstream
+git checkout -b fix/webp-upload-crash upstream/build
+```
+
+6. After making your changes, push to your fork and create a pull request:
+ ```bash
+ git push origin your-feature-branch
+ ```
+ Then visit your fork on GitHub and create a pull request targeting the `build` branch of the main repository.
+
+---
+
+## Contribution Types
+
+| Type | Good Example |
+| ----------- | ---------------------------------------------------------------------- |
+| 🐞 Bug Fix | "Fixes crash when uploading WebP files" |
+| ⚡ Feature | "Adds endpoint to replace an expensive api" |
+| 📚 Docs | "Improves deployment documentation (e.g., how to host on Netlify, AWS, Vercel, etc.)" |
+
+
+---
+
+## Final Thoughts 🧘♂️
+
+* If it's not ready, don't submit it.
+* Contributions should be helpful, obvious, and low-maintenance.
+* The goal: **make complex tasks simple for no-code users**.
+
+We're excited to see your contributions! 🎉
+
+Let's build something useful, together.
\ No newline at end of file
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000000000000000000000000000000000000..af1f946fe1916830f422305059dded0ee6ddd89f
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,215 @@
+# Base image
+FROM python:3.11-slim
+
+# Install system dependencies, build tools, and libraries
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ ca-certificates \
+ wget \
+ tar \
+ xz-utils \
+ fonts-liberation \
+ fontconfig \
+ build-essential \
+ yasm \
+ cmake \
+ meson \
+ ninja-build \
+ nasm \
+ libssl-dev \
+ libvpx-dev \
+ libx264-dev \
+ libx265-dev \
+ libnuma-dev \
+ libmp3lame-dev \
+ libopus-dev \
+ libvorbis-dev \
+ libtheora-dev \
+ libspeex-dev \
+ libfreetype6-dev \
+ libfontconfig1-dev \
+ libgnutls28-dev \
+ libaom-dev \
+ libdav1d-dev \
+ librav1e-dev \
+ libzimg-dev \
+ libwebp-dev \
+ git \
+ pkg-config \
+ autoconf \
+ automake \
+ libtool \
+ libfribidi-dev \
+ libharfbuzz-dev \
+ libnss3 \
+ libatk1.0-0 \
+ libatk-bridge2.0-0 \
+ libcups2 \
+ libxcomposite1 \
+ libxrandr2 \
+ libxdamage1 \
+ libgbm1 \
+ libasound2 \
+ libpangocairo-1.0-0 \
+ libpangoft2-1.0-0 \
+ libgtk-3-0 \
+ && rm -rf /var/lib/apt/lists/*
+
+# Install SRT from source (latest version using cmake)
+RUN git clone https://github.com/Haivision/srt.git && \
+ cd srt && \
+ mkdir build && cd build && \
+ cmake .. && \
+ make -j$(nproc) && \
+ make install && \
+ cd ../.. && rm -rf srt
+
+# Install SVT-AV1 from source
+RUN git clone https://gitlab.com/AOMediaCodec/SVT-AV1.git && \
+ cd SVT-AV1 && \
+ git checkout v0.9.0 && \
+ cd Build && \
+ cmake .. && \
+ make -j$(nproc) && \
+ make install && \
+ cd ../.. && rm -rf SVT-AV1
+
+# Install libvmaf from source
+RUN git clone https://github.com/Netflix/vmaf.git && \
+ cd vmaf/libvmaf && \
+ meson build --buildtype release && \
+ ninja -C build && \
+ ninja -C build install && \
+ cd ../.. && rm -rf vmaf && \
+ ldconfig # Update the dynamic linker cache
+
+# Manually build and install fdk-aac (since it is not available via apt-get)
+RUN git clone https://github.com/mstorsjo/fdk-aac && \
+ cd fdk-aac && \
+ autoreconf -fiv && \
+ ./configure && \
+ make -j$(nproc) && \
+ make install && \
+ cd .. && rm -rf fdk-aac
+
+# Install libunibreak (required for ASS_FEATURE_WRAP_UNICODE)
+RUN git clone https://github.com/adah1972/libunibreak.git && \
+ cd libunibreak && \
+ ./autogen.sh && \
+ ./configure && \
+ make -j$(nproc) && \
+ make install && \
+ ldconfig && \
+ cd .. && rm -rf libunibreak
+
+# Build and install libass with libunibreak support and ASS_FEATURE_WRAP_UNICODE enabled
+RUN git clone https://github.com/libass/libass.git && \
+ cd libass && \
+ autoreconf -i && \
+ ./configure --enable-libunibreak || { cat config.log; exit 1; } && \
+ mkdir -p /app && echo "Config log located at: /app/config.log" && cp config.log /app/config.log && \
+ make -j$(nproc) || { echo "Libass build failed"; exit 1; } && \
+ make install && \
+ ldconfig && \
+ cd .. && rm -rf libass
+
+# Build and install FFmpeg with all required features
+RUN git clone https://git.ffmpeg.org/ffmpeg.git ffmpeg && \
+ cd ffmpeg && \
+ git checkout n8.0 && \
+ PKG_CONFIG_PATH="/usr/lib/x86_64-linux-gnu/pkgconfig:/usr/local/lib/pkgconfig" \
+ CFLAGS="-I/usr/include/freetype2" \
+ LDFLAGS="-L/usr/lib/x86_64-linux-gnu" \
+ ./configure --prefix=/usr/local \
+ --enable-gpl \
+ --enable-pthreads \
+ --enable-neon \
+ --enable-libaom \
+ --enable-libdav1d \
+ --enable-librav1e \
+ --enable-libsvtav1 \
+ --enable-libvmaf \
+ --enable-libzimg \
+ --enable-libx264 \
+ --enable-libx265 \
+ --enable-libvpx \
+ --enable-libwebp \
+ --enable-libmp3lame \
+ --enable-libopus \
+ --enable-libvorbis \
+ --enable-libtheora \
+ --enable-libspeex \
+ --enable-libass \
+ --enable-libfreetype \
+ --enable-libharfbuzz \
+ --enable-fontconfig \
+ --enable-libsrt \
+ --enable-filter=drawtext \
+ --extra-cflags="-I/usr/include/freetype2 -I/usr/include/libpng16 -I/usr/include" \
+ --extra-ldflags="-L/usr/lib/x86_64-linux-gnu -lfreetype -lfontconfig" \
+ --enable-gnutls \
+ && make -j$(nproc) && \
+ make install && \
+ cd .. && rm -rf ffmpeg
+
+# Add /usr/local/bin to PATH (if not already included)
+ENV PATH="/usr/local/bin:${PATH}"
+
+# Copy fonts into the custom fonts directory
+# COPY ./fonts /usr/share/fonts/custom
+
+# Rebuild the font cache so that fontconfig can see the custom fonts
+# RUN fc-cache -f -v
+
+# Set work directory
+WORKDIR /app
+
+# Set environment variable for Whisper cache
+ENV WHISPER_CACHE_DIR="/app/whisper_cache"
+
+# Create cache directory (no need for chown here yet)
+RUN mkdir -p ${WHISPER_CACHE_DIR}
+
+# Copy the requirements file first to optimize caching
+COPY requirements.txt .
+
+# Install Python dependencies, upgrade pip
+RUN pip install --no-cache-dir --upgrade pip && \
+ pip install --no-cache-dir -r requirements.txt && \
+ pip install playwright && \
+ pip install jsonschema
+
+# Create the appuser
+RUN useradd -m appuser
+
+# Give appuser ownership of the /app directory (including whisper_cache)
+RUN chown appuser:appuser /app
+
+# Important: Switch to the appuser before downloading the model
+USER appuser
+
+RUN python -c "import os; print(os.environ.get('WHISPER_CACHE_DIR')); import whisper; whisper.load_model('base')"
+
+# Install Playwright Chromium browser as appuser
+RUN playwright install chromium
+
+# Copy the rest of the application code
+COPY . .
+
+
+# Expose the port the app runs on
+EXPOSE 8080
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+
+RUN echo '#!/bin/bash\n\
+gunicorn --bind 0.0.0.0:8080 \
+ --workers ${GUNICORN_WORKERS:-2} \
+ --timeout ${GUNICORN_TIMEOUT:-300} \
+ --worker-class sync \
+ --keep-alive 80 \
+ app:app' > /app/run_gunicorn.sh && \
+ chmod +x /app/run_gunicorn.sh
+
+# Run the shell script
+CMD ["/app/run_gunicorn.sh"]
\ No newline at end of file
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000000000000000000000000000000000000..48d64c3a34edf3f232ff554e80e658b73d482e8b
--- /dev/null
+++ b/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.,
+
+ 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.
+
+
+ Copyright (C)
+
+ 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 .
+
+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.
+
+ , 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.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..441c0fac13bad54d3366f6ac6ed8dbdcdf2b52c2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,9 @@
+---
+title: toolkit
+emoji: 🐨
+colorFrom: gray
+colorTo: purple
+sdk: docker
+pinned: false
+app_port: 8080
+---
\ No newline at end of file
diff --git a/app.py b/app.py
new file mode 100644
index 0000000000000000000000000000000000000000..49abb5030cec9f4036fe0bd2710a59124fdd9bec
--- /dev/null
+++ b/app.py
@@ -0,0 +1,204 @@
+# 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 Flask, request
+from queue import Queue
+from services.webhook import send_webhook
+import threading
+import uuid
+import os
+import time
+from version import BUILD_NUMBER # Import the BUILD_NUMBER
+from app_utils import log_job_status, discover_and_register_blueprints # Import the discover_and_register_blueprints function
+
+MAX_QUEUE_LENGTH = int(os.environ.get('MAX_QUEUE_LENGTH', 0))
+
+def create_app():
+ app = Flask(__name__)
+
+ # Create a queue to hold tasks
+ task_queue = Queue()
+ queue_id = id(task_queue) # Generate a single queue_id for this worker
+
+ # Function to process tasks from the queue
+ def process_queue():
+ while True:
+ job_id, data, task_func, queue_start_time = task_queue.get()
+ queue_time = time.time() - queue_start_time
+ run_start_time = time.time()
+ pid = os.getpid() # Get the PID of the actual processing thread
+
+ # Log job status as running
+ log_job_status(job_id, {
+ "job_status": "running",
+ "job_id": job_id,
+ "queue_id": queue_id,
+ "process_id": pid,
+ "response": None
+ })
+
+ response = task_func()
+ run_time = time.time() - run_start_time
+ total_time = time.time() - queue_start_time
+
+ response_data = {
+ "endpoint": response[1],
+ "code": response[2],
+ "id": data.get("id"),
+ "job_id": job_id,
+ "response": response[0] if response[2] == 200 else None,
+ "message": "success" if response[2] == 200 else response[0],
+ "pid": pid,
+ "queue_id": queue_id,
+ "run_time": round(run_time, 3),
+ "queue_time": round(queue_time, 3),
+ "total_time": round(total_time, 3),
+ "queue_length": task_queue.qsize(),
+ "build_number": BUILD_NUMBER # Add build number to response
+ }
+
+ # Log job status as done
+ log_job_status(job_id, {
+ "job_status": "done",
+ "job_id": job_id,
+ "queue_id": queue_id,
+ "process_id": pid,
+ "response": response_data
+ })
+
+ # Only send webhook if webhook_url has an actual value (not an empty string)
+ if data.get("webhook_url") and data.get("webhook_url") != "":
+ send_webhook(data.get("webhook_url"), response_data)
+
+ task_queue.task_done()
+
+ # Start the queue processing in a separate thread
+ threading.Thread(target=process_queue, daemon=True).start()
+
+ # Decorator to add tasks to the queue or bypass it
+ def queue_task(bypass_queue=False):
+ def decorator(f):
+ def wrapper(*args, **kwargs):
+ job_id = str(uuid.uuid4())
+ data = request.json if request.is_json else {}
+ pid = os.getpid() # Get PID for non-queued tasks
+ start_time = time.time()
+
+ if bypass_queue or 'webhook_url' not in data:
+
+ # Log job status as running immediately (bypassing queue)
+ log_job_status(job_id, {
+ "job_status": "running",
+ "job_id": job_id,
+ "queue_id": queue_id,
+ "process_id": pid,
+ "response": None
+ })
+
+ response = f(job_id=job_id, data=data, *args, **kwargs)
+ run_time = time.time() - start_time
+
+ response_obj = {
+ "code": response[2],
+ "id": data.get("id"),
+ "job_id": job_id,
+ "response": response[0] if response[2] == 200 else None,
+ "message": "success" if response[2] == 200 else response[0],
+ "run_time": round(run_time, 3),
+ "queue_time": 0,
+ "total_time": round(run_time, 3),
+ "pid": pid,
+ "queue_id": queue_id,
+ "queue_length": task_queue.qsize(),
+ "build_number": BUILD_NUMBER # Add build number to response
+ }
+
+ # Log job status as done
+ log_job_status(job_id, {
+ "job_status": "done",
+ "job_id": job_id,
+ "queue_id": queue_id,
+ "process_id": pid,
+ "response": response_obj
+ })
+
+ return response_obj, response[2]
+ else:
+ if MAX_QUEUE_LENGTH > 0 and task_queue.qsize() >= MAX_QUEUE_LENGTH:
+ error_response = {
+ "code": 429,
+ "id": data.get("id"),
+ "job_id": job_id,
+ "message": f"MAX_QUEUE_LENGTH ({MAX_QUEUE_LENGTH}) reached",
+ "pid": pid,
+ "queue_id": queue_id,
+ "queue_length": task_queue.qsize(),
+ "build_number": BUILD_NUMBER # Add build number to response
+ }
+
+ # Log the queue overflow error
+ log_job_status(job_id, {
+ "job_status": "done",
+ "job_id": job_id,
+ "queue_id": queue_id,
+ "process_id": pid,
+ "response": error_response
+ })
+
+ return error_response, 429
+
+ # Log job status as queued
+ log_job_status(job_id, {
+ "job_status": "queued",
+ "job_id": job_id,
+ "queue_id": queue_id,
+ "process_id": pid,
+ "response": None
+ })
+
+ task_queue.put((job_id, data, lambda: f(job_id=job_id, data=data, *args, **kwargs), start_time))
+
+ return {
+ "code": 202,
+ "id": data.get("id"),
+ "job_id": job_id,
+ "message": "processing",
+ "pid": pid,
+ "queue_id": queue_id,
+ "max_queue_length": MAX_QUEUE_LENGTH if MAX_QUEUE_LENGTH > 0 else "unlimited",
+ "queue_length": task_queue.qsize(),
+ "build_number": BUILD_NUMBER # Add build number to response
+ }, 202
+ return wrapper
+ return decorator
+
+ app.queue_task = queue_task
+
+ # Register special route for Next.js root asset paths first
+ from routes.v1.media.feedback import create_root_next_routes
+ create_root_next_routes(app)
+
+ # Use the discover_and_register_blueprints function to register all blueprints
+ discover_and_register_blueprints(app)
+
+ return app
+
+app = create_app()
+
+if __name__ == '__main__':
+ app.run(host='0.0.0.0', port=8080)
\ No newline at end of file
diff --git a/app_utils.py b/app_utils.py
new file mode 100644
index 0000000000000000000000000000000000000000..a34a6463f8ec2f2bd93f4a24ca1fa893dd727933
--- /dev/null
+++ b/app_utils.py
@@ -0,0 +1,136 @@
+# 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 request, jsonify, current_app
+from functools import wraps
+import jsonschema
+import os
+import json
+import time
+from config import LOCAL_STORAGE_PATH
+
+def validate_payload(schema):
+ def decorator(f):
+ @wraps(f)
+ def decorated_function(*args, **kwargs):
+ if not request.json:
+ return jsonify({"message": "Missing JSON in request"}), 400
+ try:
+ jsonschema.validate(instance=request.json, schema=schema)
+ except jsonschema.exceptions.ValidationError as validation_error:
+ return jsonify({"message": f"Invalid payload: {validation_error.message}"}), 400
+
+ return f(*args, **kwargs)
+ return decorated_function
+ return decorator
+
+def log_job_status(job_id, data):
+ """
+ Log job status to a file in the STORAGE_PATH/jobs folder
+
+ Args:
+ job_id (str): The unique job ID
+ data (dict): Data to write to the log file
+ """
+ jobs_dir = os.path.join(LOCAL_STORAGE_PATH, 'jobs')
+
+ # Create jobs directory if it doesn't exist
+ if not os.path.exists(jobs_dir):
+ os.makedirs(jobs_dir, exist_ok=True)
+
+ # Create or update the job log file
+ job_file = os.path.join(jobs_dir, f"{job_id}.json")
+
+ # Write data directly to file
+ with open(job_file, 'w') as f:
+ json.dump(data, f, indent=2)
+
+def queue_task_wrapper(bypass_queue=False):
+ def decorator(f):
+ def wrapper(*args, **kwargs):
+ return current_app.queue_task(bypass_queue=bypass_queue)(f)(*args, **kwargs)
+ return wrapper
+ return decorator
+
+def discover_and_register_blueprints(app, base_dir='routes'):
+ """
+ Dynamically discovers and registers all Flask blueprints in the routes directory.
+ Recursively searches all subdirectories for Python modules containing Blueprint instances.
+
+ Args:
+ app (Flask): The Flask application instance
+ base_dir (str): Base directory to start searching for blueprints (default: 'routes')
+ """
+ import importlib
+ import pkgutil
+ import inspect
+ import sys
+ import os
+ from flask import Blueprint
+ import logging
+ import glob
+
+ logger = logging.getLogger(__name__)
+ logger.info(f"Discovering blueprints in {base_dir}")
+
+ # Add the current working directory to sys.path if it's not already there
+ cwd = os.getcwd()
+ if cwd not in sys.path:
+ sys.path.insert(0, cwd)
+
+ # Get the absolute path to the base directory
+ if not os.path.isabs(base_dir):
+ base_dir = os.path.join(cwd, base_dir)
+
+ registered_blueprints = set()
+
+ # Find all Python files in the routes directory, including subdirectories
+ python_files = glob.glob(os.path.join(base_dir, '**', '*.py'), recursive=True)
+ logger.info(f"Found {len(python_files)} Python files in {base_dir}")
+
+ for file_path in python_files:
+ try:
+ # Convert file path to import path
+ rel_path = os.path.relpath(file_path, cwd)
+ # Remove .py extension
+ module_path = os.path.splitext(rel_path)[0]
+ # Convert path separators to dots for import
+ module_path = module_path.replace(os.path.sep, '.')
+
+ # Skip __init__.py files
+ if module_path.endswith('__init__'):
+ continue
+
+ #logger.info(f"Attempting to import module: {module_path}")
+
+ # Import the module
+ module = importlib.import_module(module_path)
+
+ # Find all Blueprint instances in the module
+ for name, obj in inspect.getmembers(module):
+ if isinstance(obj, Blueprint) and obj not in registered_blueprints:
+ pid = os.getpid()
+ logger.info(f"PID {pid} Registering: {module_path}")
+ app.register_blueprint(obj)
+ registered_blueprints.add(obj)
+
+ except Exception as e:
+ logger.error(f"Error importing module {module_path}: {str(e)}")
+
+ logger.info(f"PID {pid} Registered {len(registered_blueprints)} blueprints")
+ return registered_blueprints
\ No newline at end of file
diff --git a/build_number.txt b/build_number.txt
new file mode 100644
index 0000000000000000000000000000000000000000..08839f6bb296e888d311d8ea2f35f7ff82dd3f2d
--- /dev/null
+++ b/build_number.txt
@@ -0,0 +1 @@
+200
diff --git a/config.py b/config.py
new file mode 100644
index 0000000000000000000000000000000000000000..2b4e9826b54d0da41879ab9aabbdc9009a527b48
--- /dev/null
+++ b/config.py
@@ -0,0 +1,45 @@
+# 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
+
+# Retrieve the API key from environment variables
+API_KEY = os.environ.get('API_KEY')
+if not API_KEY:
+ raise ValueError("API_KEY environment variable is not set")
+
+# Storage path setting
+LOCAL_STORAGE_PATH = os.environ.get('LOCAL_STORAGE_PATH', '/tmp')
+
+# GCP environment variables
+GCP_SA_CREDENTIALS = os.environ.get('GCP_SA_CREDENTIALS', '')
+GCP_BUCKET_NAME = os.environ.get('GCP_BUCKET_NAME', '')
+
+def validate_env_vars(provider):
+
+ """ Validate the necessary environment variables for the selected storage provider """
+ required_vars = {
+ 'GCP': ['GCP_BUCKET_NAME', 'GCP_SA_CREDENTIALS'],
+ 'S3': ['S3_ENDPOINT_URL', 'S3_ACCESS_KEY', 'S3_SECRET_KEY', 'S3_BUCKET_NAME', 'S3_REGION'],
+ 'S3_DO': ['S3_ENDPOINT_URL', 'S3_ACCESS_KEY', 'S3_SECRET_KEY']
+ }
+
+ missing_vars = [var for var in required_vars[provider] if not os.getenv(var)]
+ if missing_vars:
+ raise ValueError(f"Missing environment variables for {provider} storage: {', '.join(missing_vars)}")
diff --git a/docker-compose.local.minio.n8n.md b/docker-compose.local.minio.n8n.md
new file mode 100644
index 0000000000000000000000000000000000000000..81162680fb9496bf23895f856427feeeab379d47
--- /dev/null
+++ b/docker-compose.local.minio.n8n.md
@@ -0,0 +1,317 @@
+# Local Development with MinIO and n8n
+
+This setup provides a complete local development environment for the No Code Architect Toolkit with integrated MinIO S3-compatible storage and n8n workflow automation.
+
+## What's Included
+
+- **NCA Toolkit**: Built locally from source (no pre-built image required)
+- **MinIO**: S3-compatible object storage with web console for local file management
+- **n8n**: Workflow automation platform for connecting and orchestrating services
+- **Custom Network**: All services communicate through a dedicated Docker network
+- **Persistent Storage**: Data persists between container restarts
+
+## Prerequisites
+
+- Docker and Docker Compose installed
+- Git (to clone the repository)
+- At least 2GB available RAM
+- At least 5GB available disk space
+
+---
+
+## Quick Start
+
+### 1. Prepare Environment Configuration
+
+Copy the example environment file and customize it:
+
+```bash
+cp .env.local.minio.n8n.example .env.local.minio.n8n
+```
+
+Edit `.env.local.minio.n8n` with your preferred settings. The defaults work for most local development scenarios.
+
+### 2. Start the Development Environment
+
+```bash
+docker compose -f docker-compose.local.minio.n8n.yml up -d
+```
+
+### 3. Access the Applications
+
+Once all services are running, you can access:
+
+- **NCA Toolkit API**: http://localhost:8080
+- **n8n Workflow Interface**: http://localhost:5678
+- **MinIO Console**: http://localhost:9001
+ - Username: `minioadmin`
+ - Password: `minioadmin123`
+
+### 4. Verify Setup
+
+Test the NCA Toolkit API:
+
+```bash
+curl -H "x-api-key: local-dev-key-123" http://localhost:8080/v1/toolkit/test
+```
+
+---
+
+## Environment Configuration
+
+The `.env.local.minio.n8n` file contains all necessary configuration:
+
+### Application Settings
+```env
+APP_NAME=NCAToolkit
+APP_DEBUG=true
+APP_DOMAIN=localhost:8080
+APP_URL=http://localhost:8080
+API_KEY=local-dev-key-123
+```
+
+### MinIO S3 Storage Settings
+```env
+S3_ENDPOINT_URL=http://minio:9000
+S3_ACCESS_KEY=minioadmin
+S3_SECRET_KEY=minioadmin123
+S3_REGION=us-east-1
+S3_BUCKET_NAME=nca-toolkit-local
+```
+
+### n8n Configuration
+```env
+N8N_HOST=localhost
+N8N_PORT=5678
+N8N_PROTOCOL=http
+WEBHOOK_URL=http://localhost:5678/
+```
+
+---
+
+## Service Details
+
+### NCA Toolkit (Port 8080)
+- Built from local Dockerfile
+- Connects to MinIO for file storage
+- API accessible at http://localhost:8080
+- Uses local development API key: `local-dev-key-123`
+
+### MinIO (Ports 9000, 9001)
+- **API Endpoint**: http://localhost:9000 (S3-compatible API)
+- **Web Console**: http://localhost:9001
+- **Bucket**: `nca-toolkit-local` (auto-created and configured as public)
+- **Credentials**: minioadmin / minioadmin123
+
+### n8n (Port 5678)
+- **Web Interface**: http://localhost:5678
+- **Webhook URL**: http://localhost:5678/
+- **File Sharing**: `./local-files` directory mounted for easy file access
+- Can connect to both NCA Toolkit and MinIO services
+
+---
+
+## Development Workflow
+
+### Making Code Changes
+
+1. **Edit source code** in your local directory
+2. **Rebuild the NCA Toolkit container**:
+ ```bash
+ docker compose -f docker-compose.local.minio.n8n.yml build ncat
+ docker compose -f docker-compose.local.minio.n8n.yml up -d
+ ```
+
+### Viewing Logs
+
+```bash
+# All services
+docker compose -f docker-compose.local.minio.n8n.yml logs -f
+
+# Specific service
+docker compose -f docker-compose.local.minio.n8n.yml logs -f ncat
+docker compose -f docker-compose.local.minio.n8n.yml logs -f minio
+docker compose -f docker-compose.local.minio.n8n.yml logs -f n8n
+```
+
+### Managing Storage
+
+#### Access MinIO Console
+1. Open http://localhost:9001
+2. Login with `minioadmin` / `minioadmin123`
+3. Browse the `nca-toolkit-local` bucket
+4. Upload/download files as needed
+
+#### Reset MinIO Data
+```bash
+docker compose -f docker-compose.local.minio.n8n.yml down
+docker volume rm no-code-architects-toolkit_minio_data
+docker compose -f docker-compose.local.minio.n8n.yml up -d
+```
+
+---
+
+## Service Communication
+
+All services communicate through the `nca-network` Docker network:
+
+- **n8n → NCA Toolkit**: `http://ncat:8080`
+- **n8n → MinIO**: `http://minio:9000` (S3 API)
+- **NCA Toolkit → MinIO**: `http://minio:9000` (internal network)
+
+### n8n Integration with NCA Toolkit
+
+#### Quick Test Setup
+
+1. **Access n8n**: Open http://localhost:5678
+2. **Create a new workflow**
+3. **Add an HTTP Request node** with these settings:
+ - **Method**: GET
+ - **URL**: `http://ncat:8080/v1/toolkit/test`
+ - **Headers**:
+ - Key: `x-api-key`
+ - Value: `local-dev-key-123`
+
+#### Example: Testing the Toolkit Connection
+
+**HTTP Request Node Configuration:**
+```json
+{
+ "method": "GET",
+ "url": "http://ncat:8080/v1/toolkit/test",
+ "headers": {
+ "x-api-key": "local-dev-key-123"
+ }
+}
+```
+
+**Expected Response:**
+```json
+{
+ "message": "NCA Toolkit is working correctly",
+ "status": "success"
+}
+```
+
+#### Example: Media Processing Workflow
+
+**HTTP Request Node for Media Transcription:**
+```json
+{
+ "method": "POST",
+ "url": "http://ncat:8080/v1/media/transcribe",
+ "headers": {
+ "x-api-key": "local-dev-key-123",
+ "Content-Type": "application/json"
+ },
+ "body": {
+ "media_url": "https://example.com/audio.mp3",
+ "language": "en",
+ "response_format": "json"
+ }
+}
+```
+
+#### All Available NCA Toolkit Endpoints
+
+Use the base URL `http://ncat:8080` with any of the API endpoints documented in the main README:
+
+- `http://ncat:8080/v1/toolkit/test` - Test connection
+- `http://ncat:8080/v1/media/transcribe` - Transcribe audio/video
+- `http://ncat:8080/v1/video/caption` - Add captions to videos
+- `http://ncat:8080/v1/image/screenshot/webpage` - Screenshot web pages
+- And all other endpoints listed in the main documentation
+
+#### Tips for n8n Integration
+
+1. **Always use the internal network URL**: `http://ncat:8080` (not `http://localhost:8080`)
+2. **Include the API key header**: `x-api-key: local-dev-key-123`
+3. **For file uploads**: Use the MinIO integration or webhook URLs for large files
+4. **Error handling**: Add error handling nodes to manage API timeouts or failures
+
+---
+
+## Data Persistence
+
+The following data persists between container restarts:
+
+- **Application Storage**: `storage` volume (`/app/storage`)
+- **Application Logs**: `logs` volume (`/app/logs`)
+- **MinIO Data**: `minio_data` volume
+- **n8n Workflows**: `n8n_data` volume (`/home/node/.n8n`)
+- **Shared Files**: `./local-files` directory
+
+---
+
+## Troubleshooting
+
+### Services Won't Start
+```bash
+# Check service status
+docker compose -f docker-compose.local.minio.n8n.yml ps
+
+# View error logs
+docker compose -f docker-compose.local.minio.n8n.yml logs
+```
+
+### Port Conflicts
+If ports 8080, 5678, 9000, or 9001 are already in use, modify the port mappings in `docker-compose.local.minio.n8n.yml`:
+
+```yaml
+ports:
+ - "8081:8080" # Change 8080 to 8081
+```
+
+### MinIO Bucket Issues
+The `minio-init` service automatically creates and configures the bucket. If issues occur:
+
+```bash
+# Restart the init service
+docker compose -f docker-compose.local.minio.n8n.yml restart minio-init
+
+# Check init logs
+docker compose -f docker-compose.local.minio.n8n.yml logs minio-init
+```
+
+### API Authentication Errors
+Ensure you're using the correct API key from `.env.local.minio.n8n`:
+- Default: `local-dev-key-123`
+- Header: `x-api-key: local-dev-key-123`
+
+---
+
+## Stopping the Environment
+
+```bash
+# Stop all services
+docker compose -f docker-compose.local.minio.n8n.yml down
+
+# Stop and remove volumes (deletes all data)
+docker compose -f docker-compose.local.minio.n8n.yml down -v
+```
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+│ NCA Toolkit │ │ n8n │ │ MinIO │
+│ localhost:8080│◄──►│ localhost:5678│◄──►│ localhost:9000 │
+│ │ │ │ │ (S3 API) │
+└─────────────────┘ └─────────────────┘ └─────────────────┘
+ │ │ │
+ └───────────────────────┼───────────────────────┘
+ │
+ ┌─────────────────┐
+ │ MinIO Console │
+ │ localhost:9001 │
+ └─────────────────┘
+ │
+ ┌─────────────────┐
+ │ nca-network │
+ │ (Docker Bridge) │
+ └─────────────────┘
+```
+
+This setup provides a complete local development environment with file storage, workflow automation, and the NCA Toolkit API all working together seamlessly.
\ No newline at end of file
diff --git a/docker-compose.local.minio.n8n.yml b/docker-compose.local.minio.n8n.yml
new file mode 100644
index 0000000000000000000000000000000000000000..e1ba65c66b0e1e35e28a8f0a2021662a64dfa2a0
--- /dev/null
+++ b/docker-compose.local.minio.n8n.yml
@@ -0,0 +1,79 @@
+services:
+ ncat:
+ build: .
+ env_file:
+ - .env.local.minio.n8n
+ ports:
+ - "8080:8080"
+ volumes:
+ - storage:/app/storage
+ - logs:/app/logs
+ restart: unless-stopped
+ depends_on:
+ - minio
+ - minio-init
+ networks:
+ - nca-network
+
+ minio:
+ image: minio/minio:latest
+ command: server /data --console-address ":9001"
+ ports:
+ - "9000:9000"
+ - "9001:9001"
+ environment:
+ MINIO_ROOT_USER: minioadmin
+ MINIO_ROOT_PASSWORD: minioadmin123
+ volumes:
+ - minio_data:/data
+ restart: unless-stopped
+ networks:
+ - nca-network
+
+ minio-init:
+ image: minio/mc:latest
+ depends_on:
+ - minio
+ entrypoint: >
+ /bin/sh -c "
+ sleep 5;
+ /usr/bin/mc alias set myminio http://minio:9000 minioadmin minioadmin123;
+ /usr/bin/mc mb myminio/nca-toolkit-local --ignore-existing;
+ /usr/bin/mc anonymous set public myminio/nca-toolkit-local;
+ echo 'MinIO bucket nca-toolkit-local created and configured as public';
+ "
+ networks:
+ - nca-network
+
+ n8n:
+ image: docker.n8n.io/n8nio/n8n
+ restart: unless-stopped
+ ports:
+ - "5678:5678"
+ environment:
+ - N8N_HOST=localhost
+ - N8N_PORT=5678
+ - N8N_PROTOCOL=http
+ - NODE_ENV=production
+ - WEBHOOK_URL=http://localhost:5678/
+ - GENERIC_TIMEZONE=UTC
+ - N8N_SECURE_COOKIE=false
+ volumes:
+ - n8n_data:/home/node/.n8n
+ - ./local-files:/files
+ networks:
+ - nca-network
+
+volumes:
+ storage:
+ driver: local
+ logs:
+ driver: local
+ minio_data:
+ driver: local
+ n8n_data:
+ driver: local
+
+networks:
+ nca-network:
+ driver: bridge
\ No newline at end of file
diff --git a/docker-compose.md b/docker-compose.md
new file mode 100644
index 0000000000000000000000000000000000000000..0c76864814f2c897a7b76cc5f1520b9b1ddf07b6
--- /dev/null
+++ b/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**: ``
+
+---
+
+## 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)
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000000000000000000000000000000000000..0417b9aab09d9b691512950dbc7544893f15c4c7
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,44 @@
+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
\ No newline at end of file
diff --git a/docs/adding_routes.md b/docs/adding_routes.md
new file mode 100644
index 0000000000000000000000000000000000000000..21958cfeed2126a1fab9be0f0a96bcda73280d1d
--- /dev/null
+++ b/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/`
\ No newline at end of file
diff --git a/docs/audio/concatenate.md b/docs/audio/concatenate.md
new file mode 100644
index 0000000000000000000000000000000000000000..17d953156c1cd09b9932127d76a5726a2bb86b9f
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/cloud-installation/do.md b/docs/cloud-installation/do.md
new file mode 100644
index 0000000000000000000000000000000000000000..817c4c2cbd2ccf4b15167509d73e9babaa3a7efa
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/cloud-installation/gcp.md b/docs/cloud-installation/gcp.md
new file mode 100644
index 0000000000000000000000000000000000000000..1475b6ed1785c4d8e19cbd9a77e5056ff82d4f15
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/code/execute/execute_python.md b/docs/code/execute/execute_python.md
new file mode 100644
index 0000000000000000000000000000000000000000..b31542531b2416ebab7db10934c03ff76be965ca
--- /dev/null
+++ b/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.
diff --git a/docs/ffmpeg/ffmpeg_compose.md b/docs/ffmpeg/ffmpeg_compose.md
new file mode 100644
index 0000000000000000000000000000000000000000..bd9e7864367fd4c1d7d9f5c893419d3eca3f05e7
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/image/convert/image_to_video.md b/docs/image/convert/image_to_video.md
new file mode 100644
index 0000000000000000000000000000000000000000..419a1151a95d7052f6e101353fa7c8c34ef11c74
--- /dev/null
+++ b/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.
diff --git a/docs/image/screenshot_webpage.md b/docs/image/screenshot_webpage.md
new file mode 100644
index 0000000000000000000000000000000000000000..d006bedf73326ac0cf1f41e85f2b518f8dc9998a
--- /dev/null
+++ b/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.
diff --git a/docs/media/convert/media_convert.md b/docs/media/convert/media_convert.md
new file mode 100644
index 0000000000000000000000000000000000000000..6345ecaa24841d3d070ee279bfad21568c250760
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/media/convert/media_to_mp3.md b/docs/media/convert/media_to_mp3.md
new file mode 100644
index 0000000000000000000000000000000000000000..298d39ff283d81e77c5b7c3ecd01a31af1cbd064
--- /dev/null
+++ b/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 `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.
\ No newline at end of file
diff --git a/docs/media/cut.md b/docs/media/cut.md
new file mode 100644
index 0000000000000000000000000000000000000000..f4ef1e35d098999d2fc83a4a5003d5ef96b07427
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/media/download.md b/docs/media/download.md
new file mode 100644
index 0000000000000000000000000000000000000000..c052b37f0484475c619ac09623863fb4fdce96df
--- /dev/null
+++ b/docs/media/download.md
@@ -0,0 +1,330 @@
+# 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
+ "format": "string", // Subtitle format to download (e.g., 'srt', 'vtt', 'json3')
+ "cloud_upload": boolean // Whether to upload subtitles to cloud storage (defaults to true)
+}
+```
+
+#### 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
+ },
+ "subtitles": {
+ "download": true,
+ "languages": ["en", "es-419"],
+ "format": "srt",
+ "cloud_upload": 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
+ },
+ "subtitles": {
+ "download": true,
+ "languages": ["en", "es-419"],
+ "format": "srt",
+ "cloud_upload": 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
\ No newline at end of file
diff --git a/docs/media/feedback.md b/docs/media/feedback.md
new file mode 100644
index 0000000000000000000000000000000000000000..0620e3fe4f89b70ad327cc63513f5adfc6e0c17a
--- /dev/null
+++ b/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/
+```
+
+Replace `` 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.
\ No newline at end of file
diff --git a/docs/media/generate_ass.md b/docs/media/generate_ass.md
new file mode 100644
index 0000000000000000000000000000000000000000..760476ef6f8884946f49d19d29fa4cb384fc531b
--- /dev/null
+++ b/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.
diff --git a/docs/media/media_transcribe.md b/docs/media/media_transcribe.md
new file mode 100644
index 0000000000000000000000000000000000000000..7971584860d4c4473a07ee0ad26ba83fdf9d51f5
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/docs/media/metadata.md b/docs/media/metadata.md
new file mode 100644
index 0000000000000000000000000000000000000000..cb9f0df3e3a57211c0a629dc5ec63a1733df9730
--- /dev/null
+++ b/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
+}
+```
\ No newline at end of file
diff --git a/docs/media/silence.md b/docs/media/silence.md
new file mode 100644
index 0000000000000000000000000000000000000000..b8d059b6eb17aceb8b23cfb46dcb8c07d451ad10
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/s3/upload.md b/docs/s3/upload.md
new file mode 100644
index 0000000000000000000000000000000000000000..824e54cce52588b8bacecb562d696f56c745816d
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/toolkit/authenticate.md b/docs/toolkit/authenticate.md
new file mode 100644
index 0000000000000000000000000000000000000000..0bfcfb5907fbdc33163e7be79c9103376dff7434
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/toolkit/job_status.md b/docs/toolkit/job_status.md
new file mode 100644
index 0000000000000000000000000000000000000000..c855ec7d0c975fd40ce62b7298315b2e3c2d8c25
--- /dev/null
+++ b/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: ",
+ "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.
\ No newline at end of file
diff --git a/docs/toolkit/jobs_status.md b/docs/toolkit/jobs_status.md
new file mode 100644
index 0000000000000000000000000000000000000000..1a19cf322702ef9e2b6e0562403077a20035a6d8
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/toolkit/test.md b/docs/toolkit/test.md
new file mode 100644
index 0000000000000000000000000000000000000000..a30427352aca6a70f242770b5ceb1fcffac012c3
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/video/caption_video.md b/docs/video/caption_video.md
new file mode 100644
index 0000000000000000000000000000000000000000..d8c617e70bdde116f01f6ae006f4a68b08ff3436
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/video/concatenate.md b/docs/video/concatenate.md
new file mode 100644
index 0000000000000000000000000000000000000000..eb998a7df20e8e8c2ca584f29f5f7feecef4230c
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/video/cut.md b/docs/video/cut.md
new file mode 100644
index 0000000000000000000000000000000000000000..b727ac076a9b86374a6d11af9be7dd91615d55c9
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/video/split.md b/docs/video/split.md
new file mode 100644
index 0000000000000000000000000000000000000000..2b86c6fa9d0dd1e32c155ae1638125645a56a423
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/video/thumbnail.md b/docs/video/thumbnail.md
new file mode 100644
index 0000000000000000000000000000000000000000..b572742176eff733ddf36fe15a55bf6e9cfd0d21
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/video/trim.md b/docs/video/trim.md
new file mode 100644
index 0000000000000000000000000000000000000000..b7a05baad1eb5bcfc3f2406f9cf99dea4e9922ef
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/generate_docs.py b/generate_docs.py
new file mode 100644
index 0000000000000000000000000000000000000000..befe26deb4de61d41bfb82663bffaa9cdcfdda80
--- /dev/null
+++ b/generate_docs.py
@@ -0,0 +1,329 @@
+# 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 sys
+import json
+import requests
+import time
+from pathlib import Path
+from datetime import datetime, timedelta
+
+def load_config():
+ """Load configuration from env_shell.json file."""
+ config_path = Path(__file__).parent / '.env_shell.json'
+ try:
+ with open(config_path, 'r') as f:
+ config = json.load(f)
+ return config.get('ANTHROPIC_API_KEY'), config.get('API_DOC_OUTPUT_DIR')
+ except FileNotFoundError:
+ print(f"Error: Configuration file not found at: {config_path}")
+ sys.exit(1)
+ except json.JSONDecodeError:
+ print(f"Error: Invalid JSON in configuration file: {config_path}")
+ sys.exit(1)
+ except Exception as e:
+ print(f"Error loading configuration: {str(e)}")
+ sys.exit(1)
+
+def load_app_context():
+ """Load the app.py file from the root of the repository."""
+ try:
+ # Get the root directory by going up from the current file's location
+ root_dir = Path(__file__).parent.parent
+ app_path = Path(__file__).parent / 'app.py'
+
+ if not app_path.exists():
+ print("Warning: app.py not found in repository root. Documentation will be generated without API context.")
+ return None
+
+ with open(app_path, 'r', encoding='utf-8') as f:
+ return f.read()
+ except Exception as e:
+ print(f"Warning: Could not load app.py: {str(e)}")
+ return None
+
+# The prompt template to send to Claude
+CLAUDE_PROMPT = '''
+
+ I am providing you with a Python file containing API endpoint definitions.
+
+ First, here is the main application context from app.py that shows how the API is structured and handled:
+
+** app.py below
+
+{app_context}
+
+** app.py DONE
+
+ Now, please read through the following endpoint code and analyze it in the context of the main application:
+
+**endpoint below
+
+{file_content}
+
+ Please generate detailed documentation in Markdown format as follows:
+
+ 1. Overview: Describe the purpose of the endpoint and how it fits into the overall API structure shown in app.py.
+ 2. Endpoint: Specify the URL path and HTTP method.
+ 3. Request:
+ - Headers: List any required headers, such as the x-api-key headers.
+ - Body Parameters: List the required and optional parameters, including the parameter type and purpose.
+ - Specifically study the validate_payload directive in the routes file to build the documentation
+ - Example Request: Provide a sample request payload and a sample curl command.
+ 4. Response:
+ - Success Response: Reference the endpoint and general response from the app.py to show a full sample response from the api
+ - Error Responses: Include examples of common error status codes, with example JSON responses for each.
+ 5. Error Handling:
+ - Describe common errors, like missing or invalid parameters, and indicate which status codes they produce
+ - Include any specific error handling from the main application context
+ 6. Usage Notes: Any additional notes on using the endpoint effectively.
+ 7. Common Issues: List any common issues a user might encounter.
+ 8. Best Practices: Any recommended best practices for this endpoint.
+
+ Format the documentation with markdown headings, bullet points, and code blocks.
+'''
+
+def call_claude_api(message: str, api_key: str) -> str:
+ """Make a direct API call to Claude."""
+ headers = {
+ "Content-Type": "application/json",
+ "x-api-key": api_key,
+ "anthropic-version": "2023-06-01"
+ }
+
+ data = {
+ "model": "claude-3-sonnet-20240229",
+ "max_tokens": 4096,
+ "temperature": 0,
+ "messages": [
+ {"role": "user", "content": message}
+ ]
+ }
+
+ response = requests.post(
+ "https://api.anthropic.com/v1/messages",
+ headers=headers,
+ json=data
+ )
+
+ if response.status_code != 200:
+ raise Exception(f"API call failed with status {response.status_code}: {response.text}")
+
+ return response.json()["content"][0]["text"]
+
+def should_skip_doc_generation(output_file: Path, force: bool = False) -> bool:
+ """
+ Check if documentation was updated in the last 24 hours.
+
+ Args:
+ output_file: Path to the output markdown file
+ force: If True, always return False to force generation
+
+ Returns:
+ bool: True if file was updated in the last 24 hours and not forced, False otherwise
+ """
+ # If force flag is provided, never skip
+ if force:
+ return False
+
+ if not output_file.exists():
+ return False
+
+ # Get file modification time
+ mod_time = datetime.fromtimestamp(output_file.stat().st_mtime)
+
+ # Check if file was modified in the last 24 hours
+ time_threshold = datetime.now() - timedelta(hours=24)
+
+ return mod_time > time_threshold
+
+def process_single_file(source_file: Path, output_path: Path, api_key: str, force: bool = False):
+ """
+ Process a single Python file.
+
+ Args:
+ source_file: Path to the source Python file
+ output_path: Path to output the markdown file
+ api_key: Anthropic API key
+ force: If True, generate docs even if they were updated recently
+ """
+ try:
+ # Create output file path
+ if output_path.is_dir():
+ output_file = output_path / source_file.with_suffix('.md').name
+ else:
+ output_file = output_path
+
+ # Check if docs were recently updated
+ if should_skip_doc_generation(output_file, force):
+ print(f"Skipping {source_file} - documentation updated within the last 24 hours")
+ return
+
+ # Read the source file
+ with open(source_file, 'r', encoding='utf-8') as f:
+ file_content = f.read()
+
+ # Load app.py context
+ app_context = load_app_context()
+ if app_context is None:
+ app_context = "No app.py context available."
+
+ # Create the full prompt
+ message = CLAUDE_PROMPT.format(
+ app_context=app_context,
+ file_content=file_content
+ )
+
+ # Get documentation from Claude
+ markdown_content = call_claude_api(message, api_key)
+
+ # Create necessary directories
+ output_file.parent.mkdir(parents=True, exist_ok=True)
+
+ # Write the markdown content (will overwrite if exists)
+ with open(output_file, 'w', encoding='utf-8') as f:
+ f.write(markdown_content)
+
+ print(f"Generated documentation for: {source_file}")
+ print(f"Output saved to: {output_file}")
+
+ except Exception as e:
+ print(f"Error processing {source_file}: {str(e)}", file=sys.stderr)
+
+def process_directory(source_dir: Path, output_dir: Path, api_key: str, force: bool = False):
+ """Process all Python files in the source directory recursively."""
+ # Track statistics
+ total_files = 0
+ processed_files = 0
+ skipped_files = 0
+ error_files = 0
+
+ start_time = time.time()
+
+ # Walk through all files in source directory
+ for root, _, files in os.walk(source_dir):
+ for file in files:
+ if file.endswith('.py'):
+ # Get the source file path
+ source_file = Path(root) / file
+ total_files += 1
+
+ try:
+ # Calculate relative path to maintain directory structure
+ rel_path = source_file.relative_to(source_dir)
+ output_file = output_dir / rel_path.with_suffix('.md')
+
+ # Create necessary directories
+ output_file.parent.mkdir(parents=True, exist_ok=True)
+
+ # Check if we should skip this file
+ if should_skip_doc_generation(output_file, force):
+ print(f"Skipping {source_file} - documentation updated within the last 24 hours")
+ skipped_files += 1
+ continue
+
+ # Process the file
+ process_single_file(source_file, output_file, api_key, force)
+ processed_files += 1
+
+ except Exception as e:
+ print(f"Error processing {source_file}: {str(e)}", file=sys.stderr)
+ error_files += 1
+
+ # Print summary
+ elapsed_time = time.time() - start_time
+ print("\nDocumentation Generation Summary:")
+ print(f"Total Python files found: {total_files}")
+ print(f"Files processed: {processed_files}")
+ print(f"Files skipped (updated in last 24h): {skipped_files}")
+ print(f"Files with errors: {error_files}")
+ print(f"Total time: {elapsed_time:.2f} seconds")
+
+def main():
+ # Check if --force flag is provided
+ force_generation = False
+ source_path_arg = None
+
+ for arg in sys.argv[1:]:
+ if arg == "--force":
+ force_generation = True
+ else:
+ source_path_arg = arg
+
+ if not source_path_arg:
+ print("Usage: python script.py [--force]")
+ print("Note: source_path can be either a single .py file or a directory")
+ print("Options:")
+ print(" --force: Generate documentation even if it was updated within 24 hours")
+ print("\nPlease ensure .env_shell.json exists in the same directory with:")
+ print(" ANTHROPIC_API_KEY: Your Anthropic API key")
+ print(" API_DOC_OUTPUT_DIR: Directory where documentation will be saved")
+ sys.exit(1)
+
+ # Load configuration from JSON file
+ api_key, output_dir = load_config()
+
+ # Validate configuration
+ if not api_key:
+ print("Error: ANTHROPIC_API_KEY not found in configuration file")
+ sys.exit(1)
+
+ if not output_dir:
+ print("Error: API_DOC_OUTPUT_DIR not found in configuration file")
+ sys.exit(1)
+
+ output_path = Path(output_dir)
+
+ # Get and validate source path
+ source_path = Path(source_path_arg)
+
+ if not source_path.exists():
+ print(f"Error: Source path does not exist: {source_path}")
+ sys.exit(1)
+
+ if source_path.is_file() and not source_path.suffix == '.py':
+ print("Error: Source file must be a Python file (.py)")
+ sys.exit(1)
+
+ # Create output directory if it doesn't exist
+ output_path.mkdir(parents=True, exist_ok=True)
+
+ print(f"Starting documentation generation...")
+ print(f"Source: {source_path}")
+ print(f"Output: {output_path}")
+ if force_generation:
+ print(f"Force flag enabled: Will generate all documentation regardless of last update time.\n")
+ else:
+ print(f"Note: Files updated within the last 24 hours will be skipped (use --force to override).\n")
+
+ # Process based on source type
+ if source_path.is_file():
+ # For a single file
+ output_file = output_path / source_path.with_suffix('.md').name if output_path.is_dir() else output_path
+
+ # Check if should skip
+ if should_skip_doc_generation(output_file, force_generation):
+ print(f"Skipping {source_path} - documentation updated within the last 24 hours")
+ else:
+ process_single_file(source_path, output_path, api_key, force_generation)
+ else:
+ process_directory(source_path, output_path, api_key, force_generation)
+
+if __name__ == "__main__":
+ main()
\ No newline at end of file
diff --git a/generate_vector.sh b/generate_vector.sh
new file mode 100755
index 0000000000000000000000000000000000000000..53c3f80bcca753021639ce7b946e2941dbc872df
--- /dev/null
+++ b/generate_vector.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+
+for file in $(find . -type f \( -iname "*.md" -o -iname "*.txt" -o -name "*.py" -o -name "Dockerfile" \) \
+ -not -name "audio_mixing.py" \
+ -not -name "authenticate.py" \
+ -not -name "authentication.py" \
+ -not -name "caption_video.py" \
+ -not -name "combine_videos.py" \
+ -not -name "extract_keyframes.py" \
+ -not -name "ffmpeg_toolkit.py" \
+ -not -name "file_management.py" \
+ -not -name "image_to_video.py" \
+ -not -name "media_to_mp3.py" \
+ -not -name "transcribe_media.py" \
+ -not -name "transcription.py"); do
+ echo "File: $file" >> "NCA Toolkit API Vector Doc.txt"
+ echo -e "\n\n" >> "NCA Toolkit API Vector Doc.txt"
+ cat "$file" >> "NCA Toolkit API Vector Doc.txt"
+ echo -e "\n\n" >> "NCA Toolkit API Vector Doc.txt"
+done
\ No newline at end of file
diff --git a/local.sh b/local.sh
new file mode 100755
index 0000000000000000000000000000000000000000..76928f7c4dea06bd2aaa991ca70577357b9d595c
--- /dev/null
+++ b/local.sh
@@ -0,0 +1,41 @@
+#!/bin/bash
+
+# Stop all running Docker containers
+echo "Stopping no-code-architects running Docker containers..."
+docker stop $(docker ps -a --filter ancestor=no-code-architects-toolkit:testing --format="{{.ID}}")
+
+# Build the Docker image
+echo "Building Docker image..."
+docker build -t no-code-architects-toolkit:testing .
+
+# Read variables from .variables file
+echo "Reading environment variables..."
+VARS=$(cat .env_variables.json)
+
+# Function to escape JSON strings for bash
+escape_json() {
+ echo "$1" | sed 's/"/\\"/g'
+}
+
+# Build the docker run command with environment variables
+CMD="docker run -p 8080:8080"
+
+# Add environment variables from JSON
+for key in $(echo "$VARS" | jq -r 'keys[]'); do
+ value=$(echo "$VARS" | jq -r --arg k "$key" '.[$k]')
+
+ # Handle nested JSON (specifically for GCP_SA_CREDENTIALS)
+ if [[ "$key" == "GCP_SA_CREDENTIALS" ]]; then
+ value=$(echo "$VARS" | jq -r --arg k "$key" '.[$k]')
+ value=$(escape_json "$value")
+ fi
+
+ CMD="$CMD -e $key=\"$value\""
+done
+
+# Complete the command
+CMD="$CMD no-code-architects-toolkit:testing"
+
+# Run the Docker container
+echo "Running Docker container..."
+eval "$CMD"
\ No newline at end of file
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000000000000000000000000000000000000..dc1732461e30e0465b4e514ef7c81073ef512444
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,34 @@
+Flask
+Werkzeug
+requests
+ffmpeg-python
+gunicorn
+pandas
+APScheduler
+srt
+numpy
+google-auth
+google-auth-oauthlib
+google-auth-httplib2
+google-api-python-client
+google-cloud-storage
+psutil
+boto3
+Pillow
+matplotlib
+yt-dlp
+
+
+beautifulsoup4
+openpyxl
+seaborn
+scikit-learn
+scipy
+pytesseract
+face-recognition
+mediapipe
+qrcode[pil]
+pdf2image
+reportlab
+pydub
+librosa
diff --git a/routes/audio_mixing.py b/routes/audio_mixing.py
new file mode 100644
index 0000000000000000000000000000000000000000..fa1a781ae4dcf3e50081769df32d00584e8abe59
--- /dev/null
+++ b/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
diff --git a/routes/authenticate.py b/routes/authenticate.py
new file mode 100644
index 0000000000000000000000000000000000000000..f8df31241622e4614ede286b4c3b4680ae17ff29
--- /dev/null
+++ b/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
diff --git a/routes/caption_video.py b/routes/caption_video.py
new file mode 100644
index 0000000000000000000000000000000000000000..8e886b20a00b832f55afb7e13b834b02b70b6034
--- /dev/null
+++ b/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
diff --git a/routes/combine_videos.py b/routes/combine_videos.py
new file mode 100644
index 0000000000000000000000000000000000000000..0952179920e674681fde7d132047893c4d5f1b66
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/routes/extract_keyframes.py b/routes/extract_keyframes.py
new file mode 100644
index 0000000000000000000000000000000000000000..764f7b1c54093040ce28b3a00eed402940e4a67b
--- /dev/null
+++ b/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
diff --git a/routes/gdrive_upload.py b/routes/gdrive_upload.py
new file mode 100644
index 0000000000000000000000000000000000000000..e3a42a23e5818af556ae454b46ff2adc8036be55
--- /dev/null
+++ b/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()
\ No newline at end of file
diff --git a/routes/image_to_video.py b/routes/image_to_video.py
new file mode 100644
index 0000000000000000000000000000000000000000..5a22372036827a4ebf2961d40c3a3861c7873b3d
--- /dev/null
+++ b/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
diff --git a/routes/media_to_mp3.py b/routes/media_to_mp3.py
new file mode 100644
index 0000000000000000000000000000000000000000..8513c6966e4e00f9bce0806410f3da442b8a1f79
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/routes/transcribe_media.py b/routes/transcribe_media.py
new file mode 100644
index 0000000000000000000000000000000000000000..78f839f51a49506825e65e4f6fe307ed5ca0ff4b
--- /dev/null
+++ b/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
diff --git a/routes/v1/audio/concatenate.py b/routes/v1/audio/concatenate.py
new file mode 100644
index 0000000000000000000000000000000000000000..8c5565a2b8c851792a786fd23615440ae7390b9f
--- /dev/null
+++ b/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
diff --git a/routes/v1/code/execute/execute_python.py b/routes/v1/code/execute/execute_python.py
new file mode 100644
index 0000000000000000000000000000000000000000..13dc07574776658a5d8a2e1b48efab3524355d13
--- /dev/null
+++ b/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)
\ No newline at end of file
diff --git a/routes/v1/ffmpeg/ffmpeg_compose.py b/routes/v1/ffmpeg/ffmpeg_compose.py
new file mode 100644
index 0000000000000000000000000000000000000000..ce08752b5af4b52940215ebe95fb42917808c367
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/routes/v1/image/convert/image_to_video.py b/routes/v1/image/convert/image_to_video.py
new file mode 100644
index 0000000000000000000000000000000000000000..85fe42da8ec31f76b051826284199a33f95d915f
--- /dev/null
+++ b/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
diff --git a/routes/v1/image/screenshot_webpage.py b/routes/v1/image/screenshot_webpage.py
new file mode 100644
index 0000000000000000000000000000000000000000..63d4469688b85bbece9025806e54130bce148432
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/routes/v1/media/convert/media_convert.py b/routes/v1/media/convert/media_convert.py
new file mode 100644
index 0000000000000000000000000000000000000000..02a184c0aaf58e032489c9223f575ecf347bfc20
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/routes/v1/media/convert/media_to_mp3.py b/routes/v1/media/convert/media_to_mp3.py
new file mode 100644
index 0000000000000000000000000000000000000000..6a84ac90010fa8ea1016b0e2ce2c6cfddf4fcc92
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/routes/v1/media/download.py b/routes/v1/media/download.py
new file mode 100644
index 0000000000000000000000000000000000000000..55e417da28d91c56282263de0d56b622d1fdc2f5
--- /dev/null
+++ b/routes/v1/media/download.py
@@ -0,0 +1,289 @@
+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
+import requests
+
+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"}},
+ "format": {
+ "type": "string",
+ "enum": [
+ "srt", # SubRip Subtitle (most common)
+ "vtt", # Web Video Text Tracks
+ "json3" # YouTube's JSON format
+ ]
+ },
+ "cloud_upload": {"type": "boolean"}
+ }
+ },
+ "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('format'):
+ ydl_opts['subtitlesformat'] = subtitle_options['format']
+
+ # 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
+
+ # Process subtitles if available
+ if 'subtitles' in info and subtitle_options.get('download', False):
+ logger.info(f"Job {job_id}: Found subtitles in info: {info['subtitles']}")
+ response["subtitles"] = {} # Changed from array to object
+ requested_languages = subtitle_options.get('languages', [])
+ requested_format = subtitle_options.get('format', 'srt')
+ subtitle_cloud_upload = subtitle_options.get('cloud_upload', True) # Default to True
+
+ # If no languages specified, use all available languages
+ if not requested_languages:
+ requested_languages = list(info['subtitles'].keys())
+ logger.info(f"Job {job_id}: No languages specified, using all available: {requested_languages}")
+
+ for lang, subtitle_list in info['subtitles'].items():
+ # Skip if language not in requested list
+ if lang not in requested_languages:
+ continue
+
+ try:
+ logger.info(f"Job {job_id}: Processing subtitle for language {lang}")
+ # Find the requested format
+ subtitle_data = None
+ for subtitle in subtitle_list:
+ if subtitle['ext'] == requested_format:
+ subtitle_data = subtitle
+ break
+
+ if not subtitle_data:
+ logger.warning(f"Job {job_id}: Requested format {requested_format} not available for {lang}")
+ continue
+
+ # If cloud upload is requested, download and upload the subtitle
+ if subtitle_cloud_upload:
+ try:
+ subtitle_path = download_file(subtitle_data['url'], temp_dir)
+ cloud_url = upload_file(subtitle_path)
+ subtitle_data['url'] = cloud_url
+ except Exception as e:
+ logger.warning(f"Job {job_id}: Failed to download subtitle for {lang}: {str(e)}")
+ continue
+
+ # Add subtitle data to response using language code as key
+ response["subtitles"][lang] = subtitle_data
+ logger.info(f"Job {job_id}: Successfully processed subtitle for {lang}")
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error processing subtitle: {str(e)}")
+ continue
+ else:
+ logger.info(f"Job {job_id}: No subtitles found in info or download not requested")
+
+ 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
\ No newline at end of file
diff --git a/routes/v1/media/feedback.py b/routes/v1/media/feedback.py
new file mode 100644
index 0000000000000000000000000000000000000000..dbadfaabc7adb2b3658498ee78ab1451cbd673f1
--- /dev/null
+++ b/routes/v1/media/feedback.py
@@ -0,0 +1,185 @@
+from flask import Blueprint, send_from_directory, current_app, request, redirect, url_for, make_response
+import os
+import mimetypes
+import re
+from services.v1.media.feedback.feedback import get_feedback_path
+
+# Ensure correct MIME types for Next.js assets
+mimetypes.add_type('application/javascript', '.js')
+mimetypes.add_type('text/css', '.css')
+mimetypes.add_type('font/woff2', '.woff2')
+
+# Base URL path for assets
+BASE_PATH = '/v1/media/feedback'
+
+v1_media_feedback_bp = Blueprint('v1_media_feedback', __name__, url_prefix='/v1/media/feedback', static_folder=None)
+
+def create_root_next_routes(app):
+ """
+ Create routes at the application root level to handle Next.js asset paths
+ This helps with client-side navigation and dynamic asset loading
+ """
+ @app.route('/_next/')
+ def root_next_static(path):
+ """Redirect root-level Next.js requests to our namespaced route"""
+ return redirect(f'{BASE_PATH}/_next/{path}')
+
+ @app.route('/favicon.ico')
+ def root_favicon():
+ """Redirect favicon requests to our namespaced route"""
+ return redirect(f'{BASE_PATH}/favicon.ico')
+
+ @app.route('/logo.png')
+ def root_logo():
+ """Redirect logo requests to our namespaced route"""
+ return redirect(f'{BASE_PATH}/logo.png')
+
+@v1_media_feedback_bp.route('', methods=['GET'])
+def serve_feedback_page():
+ """
+ Serve the feedback HTML page with path corrections
+ """
+ try:
+ # Get the feedback static files directory path
+ feedback_path = get_feedback_path()
+
+ # Read the HTML file content
+ with open(os.path.join(feedback_path, 'index.html'), 'r') as f:
+ content = f.read()
+
+ # Fix paths in the HTML content to include the base path
+ # Replace resource paths
+ content = content.replace('href="/_next/', f'href="{BASE_PATH}/_next/')
+ content = content.replace('src="/_next/', f'src="{BASE_PATH}/_next/')
+ content = content.replace('href="/favicon.ico', f'href="{BASE_PATH}/favicon.ico')
+ content = content.replace('href="/logo.png', f'href="{BASE_PATH}/logo.png')
+ content = content.replace('src="/logo.png', f'src="{BASE_PATH}/logo.png')
+
+ # Create response with modified content
+ response = make_response(content)
+ response.headers['Content-Type'] = 'text/html'
+ return response
+ except Exception as e:
+ current_app.logger.error(f"Error serving index.html: {str(e)}")
+ return str(e), 'serve_feedback_page', 500
+
+@v1_media_feedback_bp.route('/_next/', methods=['GET'])
+def serve_next_static(path):
+ """
+ Serve Next.js static files from _next directory
+ """
+ try:
+ feedback_path = get_feedback_path()
+ file_path = os.path.join('_next', path)
+ full_path = os.path.join(feedback_path, file_path)
+
+ # Get the file extension for MIME type detection
+ _, ext = os.path.splitext(path)
+
+ # Handle special case for JS files to fix paths
+ if ext == '.js':
+ if os.path.exists(full_path):
+ try:
+ with open(full_path, 'r') as f:
+ content = f.read()
+
+ # Fix paths in JS files that might reference other assets
+ if '/_next/' in content:
+ content = content.replace('href:"/_next/', f'href:"{BASE_PATH}/_next/')
+ content = content.replace('src:"/_next/', f'src:"{BASE_PATH}/_next/')
+
+ # Create response with modified content
+ response = make_response(content)
+ response.headers['Content-Type'] = 'application/javascript'
+ return response
+ except UnicodeDecodeError:
+ # If we can't read as text, serve as binary
+ pass
+
+ # Handle special case for font files
+ if ext == '.woff2' or ext == '.woff' or ext == '.ttf' or ext == '.eot':
+ response = send_from_directory(feedback_path, file_path)
+ if ext == '.woff2':
+ response.headers['Content-Type'] = 'font/woff2'
+ elif ext == '.woff':
+ response.headers['Content-Type'] = 'font/woff'
+ elif ext == '.ttf':
+ response.headers['Content-Type'] = 'font/ttf'
+ elif ext == '.eot':
+ response.headers['Content-Type'] = 'application/vnd.ms-fontobject'
+
+ # Add CORS headers for font files
+ response.headers['Access-Control-Allow-Origin'] = '*'
+ return response
+
+ # For other files, serve directly
+ mime_type = mimetypes.types_map.get(ext, 'application/octet-stream')
+
+ response = send_from_directory(feedback_path, file_path)
+ response.headers['Content-Type'] = mime_type
+
+ # Add CORS headers for font files
+ if ext == '.woff2' or ext == '.woff' or ext == '.ttf' or ext == '.eot':
+ response.headers['Access-Control-Allow-Origin'] = '*'
+
+ return response
+ except Exception as e:
+ current_app.logger.error(f"Error serving Next.js static file {path}: {str(e)}")
+ return str(e), 'serve_next_static', 500
+
+@v1_media_feedback_bp.route('/', methods=['GET'])
+def serve_feedback_static(filename):
+ """
+ Serve static files for the feedback page (CSS, JS, images, etc.)
+ """
+ try:
+ # Get the feedback static files directory path
+ feedback_path = get_feedback_path()
+
+ # Special handling for CSS files that might need path rewriting
+ _, ext = os.path.splitext(filename)
+ if ext == '.css':
+ full_path = os.path.join(feedback_path, filename)
+ if os.path.exists(full_path):
+ with open(full_path, 'r') as f:
+ content = f.read()
+
+ # Rewrite paths in CSS if needed
+ if 'url(/_next/' in content:
+ content = content.replace('url(/_next/', f'url({BASE_PATH}/_next/')
+
+ # Create response with modified content
+ response = make_response(content)
+ response.headers['Content-Type'] = 'text/css'
+ return response
+
+ # Handle JavaScript files
+ if ext == '.js':
+ full_path = os.path.join(feedback_path, filename)
+ if os.path.exists(full_path):
+ with open(full_path, 'r') as f:
+ content = f.read()
+
+ # Rewrite paths in JS if needed
+ if '/_next/' in content:
+ content = content.replace('href:"/_next/', f'href:"{BASE_PATH}/_next/')
+ content = content.replace('src:"/_next/', f'src:"{BASE_PATH}/_next/')
+
+ # Create response with modified content
+ response = make_response(content)
+ response.headers['Content-Type'] = 'application/javascript'
+ return response
+
+ # For image and other static files
+ mime_type = mimetypes.types_map.get(ext, 'application/octet-stream')
+
+ # Serve the requested static file
+ response = send_from_directory(feedback_path, filename)
+ response.headers['Content-Type'] = mime_type
+ return response
+ except FileNotFoundError:
+ current_app.logger.error(f"Static file not found: {filename}")
+ return "File not found", 404
+ except Exception as e:
+ current_app.logger.error(f"Error serving static file {filename}: {str(e)}")
+ return str(e), 500
diff --git a/routes/v1/media/generate_ass.py b/routes/v1/media/generate_ass.py
new file mode 100644
index 0000000000000000000000000000000000000000..72a67f819a0dbc3e79fcc0d9a5c82cb933c13f41
--- /dev/null
+++ b/routes/v1/media/generate_ass.py
@@ -0,0 +1,144 @@
+from flask import Blueprint, jsonify, request
+from app_utils import validate_payload, queue_task_wrapper
+import logging
+from services.ass_toolkit import generate_ass_captions_v1
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+import os
+import requests
+
+v1_media_generate_ass_bp = Blueprint('v1_media_generate_ass', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_media_generate_ass_bp.route('/v1/media/generate/ass', methods=['POST'])
+@authenticate
+@validate_payload({
+ "type": "object",
+ "properties": {
+ "media_url": {"type": "string", "format": "uri"},
+ "canvas_width": {"type": "integer", "minimum": 1},
+ "canvas_height": {"type": "integer", "minimum": 1},
+ "settings": {
+ "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", "karaoke", "highlight", "underline", "word_by_word"]
+ },
+ "outline_width": {"type": "integer"},
+ "spacing": {"type": "integer"},
+ "angle": {"type": "integer"},
+ "shadow_offset": {"type": "integer"}
+ },
+ "additionalProperties": False
+ },
+ "replace": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "find": {"type": "string"},
+ "replace": {"type": "string"}
+ },
+ "required": ["find", "replace"]
+ }
+ },
+ "exclude_time_ranges": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "start": { "type": "string" },
+ "end": { "type": "string" }
+ },
+ "required": ["start", "end"],
+ "additionalProperties": False
+ }
+ },
+ "language": {"type": "string"},
+ "webhook_url": {"type": "string", "format": "uri"},
+ "id": {"type": "string"}
+ },
+ "additionalProperties": False,
+ "required": ["media_url"],
+ "oneOf": [
+ { "required": ["canvas_width", "canvas_height"] },
+ { "not": { "anyOf": [ { "required": ["canvas_width"] }, { "required": ["canvas_height"] } ] } }
+ ]
+
+})
+
+@queue_task_wrapper(bypass_queue=False)
+def generate_ass_v1(job_id, data):
+ media_url = data['media_url']
+ settings = data.get('settings', {})
+ replace = data.get('replace', [])
+ exclude_time_ranges = data.get('exclude_time_ranges', [])
+ webhook_url = data.get('webhook_url')
+ id = data.get('id')
+ language = data.get('language', 'auto')
+ canvas_width = data.get('canvas_width')
+ canvas_height = data.get('canvas_height')
+
+ logger.info(f"Job {job_id}: Received ASS generation request for {media_url}")
+ logger.info(f"Job {job_id}: Settings received: {settings}")
+ logger.info(f"Job {job_id}: Replace rules received: {replace}")
+ logger.info(f"Job {job_id}: Exclude time ranges received: {exclude_time_ranges}")
+
+ try:
+ output = generate_ass_captions_v1(
+ media_url,
+ captions=None,
+ settings=settings,
+ replace=replace,
+ exclude_time_ranges=exclude_time_ranges,
+ job_id=job_id,
+ language=language,
+ PlayResX=canvas_width,
+ PlayResY=canvas_height
+ )
+ if isinstance(output, dict) and 'error' in output:
+ if 'available_fonts' in output:
+ return {"error": output['error'], "available_fonts": output['available_fonts']}, "/v1/media/generate/ass", 400
+ else:
+ return {"error": output['error']}, "/v1/media/generate/ass", 400
+
+ ass_path = output
+ logger.info(f"Job {job_id}: ASS file generated at {ass_path}")
+
+ cloud_url = upload_file(ass_path)
+ logger.info(f"Job {job_id}: ASS file uploaded to cloud storage: {cloud_url}")
+
+ os.remove(ass_path)
+ logger.info(f"Job {job_id}: Cleaned up local ASS file")
+
+ return cloud_url, "/v1/media/generate/ass", 200
+
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error during ASS generation process - {str(e)}", exc_info=True)
+ return {"error": str(e)}, "/v1/media/generate/ass", 500
diff --git a/routes/v1/media/media_transcribe.py b/routes/v1/media/media_transcribe.py
new file mode 100644
index 0000000000000000000000000000000000000000..9609210bc9aec4b1b8434ecc62235919a21868b5
--- /dev/null
+++ b/routes/v1/media/media_transcribe.py
@@ -0,0 +1,108 @@
+# 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.v1.media.media_transcribe import process_transcribe_media
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+
+v1_media_transcribe_bp = Blueprint('v1_media_transcribe', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_media_transcribe_bp.route('/v1/media/transcribe', methods=['POST'])
+@authenticate
+@validate_payload({
+ "type": "object",
+ "properties": {
+ "media_url": {"type": "string", "format": "uri"},
+ "task": {"type": "string", "enum": ["transcribe", "translate"]},
+ "include_text": {"type": "boolean"},
+ "include_srt": {"type": "boolean"},
+ "include_segments": {"type": "boolean"},
+ "word_timestamps": {"type": "boolean"},
+ "response_type": {"type": "string", "enum": ["direct", "cloud"]},
+ "language": {"type": "string"},
+ "webhook_url": {"type": "string", "format": "uri"},
+ "id": {"type": "string"},
+ "words_per_line": {"type": "integer", "minimum": 1}
+ },
+ "required": ["media_url"],
+ "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def transcribe(job_id, data):
+ media_url = data['media_url']
+ task = data.get('task', 'transcribe')
+ include_text = data.get('include_text', True)
+ include_srt = data.get('include_srt', False)
+ include_segments = data.get('include_segments', False)
+ word_timestamps = data.get('word_timestamps', False)
+ response_type = data.get('response_type', 'direct')
+ language = data.get('language', None)
+ webhook_url = data.get('webhook_url')
+ id = data.get('id')
+ words_per_line = data.get('words_per_line', None)
+
+ logger.info(f"Job {job_id}: Received transcription request for {media_url}")
+
+ try:
+ result = process_transcribe_media(media_url, task, include_text, include_srt, include_segments, word_timestamps, response_type, language, job_id, words_per_line)
+ 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 response_type == "direct":
+
+ result_json = {
+ "text": result[0],
+ "srt": result[1],
+ "segments": result[2],
+ "text_url": None,
+ "srt_url": None,
+ "segments_url": None,
+ }
+
+ return result_json, "/v1/transcribe/media", 200
+
+ else:
+
+ cloud_urls = {
+ "text": None,
+ "srt": None,
+ "segments": None,
+ "text_url": upload_file(result[0]) if include_text is True else None,
+ "srt_url": upload_file(result[1]) if include_srt is True else None,
+ "segments_url": upload_file(result[2]) if include_segments is True else None,
+ }
+
+ if include_text is True:
+ os.remove(result[0]) # Remove the temporary file after uploading
+
+ if include_srt is True:
+ os.remove(result[1])
+
+ if include_segments is True:
+ os.remove(result[2])
+
+ return cloud_urls, "/v1/transcribe/media", 200
+
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error during transcription process - {str(e)}")
+ return str(e), "/v1/transcribe/media", 500
diff --git a/routes/v1/media/metadata.py b/routes/v1/media/metadata.py
new file mode 100644
index 0000000000000000000000000000000000000000..f2ee861730632bf31850fce613208b6d26dd7f21
--- /dev/null
+++ b/routes/v1/media/metadata.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, request, jsonify
+from app_utils import validate_payload, queue_task_wrapper
+import logging
+from services.v1.media.metadata import get_media_metadata
+from services.authentication import authenticate
+
+# Set up logger
+logger = logging.getLogger(__name__)
+
+# Create blueprint
+v1_media_metadata_bp = Blueprint('v1_media_metadata', __name__)
+
+@v1_media_metadata_bp.route('/v1/media/metadata', methods=['POST'])
+@authenticate
+@validate_payload({
+ "type": "object",
+ "properties": {
+ "media_url": {"type": "string", "format": "uri"},
+ "webhook_url": {"type": "string", "format": "uri"},
+ "id": {"type": "string"}
+ },
+ "required": ["media_url"],
+ "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=True) # Set to execute immediately instead of queueing
+def media_metadata(job_id, data):
+ """
+ Extract metadata from a media file, including video and audio properties.
+
+ Expected input:
+ {
+ "media_url": "https://example.com/media.mp4",
+ "webhook_url": "https://example.com/webhook" (optional),
+ "id": "custom-id" (optional)
+ }
+
+ Returns metadata including filesize, duration, video/audio codec info,
+ resolution, frame rate, and bitrates.
+ """
+ media_url = data['media_url']
+ logger.info(f"Job {job_id}: Received metadata request for {media_url}")
+
+ try:
+ # Extract metadata from the media file
+ metadata = get_media_metadata(media_url, job_id)
+ logger.info(f"Job {job_id}: Successfully extracted metadata")
+
+ # Return the metadata directly
+ return metadata, "/v1/media/metadata", 200
+
+ except Exception as e:
+ error_message = str(e)
+ logger.error(f"Job {job_id}: Error extracting metadata - {error_message}")
+ return error_message, "/v1/media/metadata", 500
\ No newline at end of file
diff --git a/routes/v1/media/silence.py b/routes/v1/media/silence.py
new file mode 100644
index 0000000000000000000000000000000000000000..9f4acc1158fa9ab9b7ee33e1138650611ec853e0
--- /dev/null
+++ b/routes/v1/media/silence.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.media.silence import detect_silence
+from services.authentication import authenticate
+
+v1_media_silence_bp = Blueprint('v1_media_silence', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_media_silence_bp.route('/v1/media/silence', methods=['POST'])
+@authenticate
+@validate_payload({
+ "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
+})
+@queue_task_wrapper(bypass_queue=False)
+def silence(job_id, data):
+ """Detect silence in a media file and return the silence intervals."""
+ media_url = data['media_url']
+ start_time = data.get('start', None) # None = start from beginning
+ end_time = data.get('end', None) # None = process until end
+ noise_threshold = data.get('noise', '-30dB')
+ min_duration = data['duration'] # Required parameter
+ mono = data.get('mono', True) # Default to True
+
+ logger.info(f"Job {job_id}: Received silence detection request for {media_url}")
+
+ try:
+ silence_intervals = detect_silence(
+ media_url=media_url,
+ start_time=start_time,
+ end_time=end_time,
+ noise_threshold=noise_threshold,
+ min_duration=min_duration,
+ mono=mono,
+ job_id=job_id
+ )
+
+ logger.info(f"Job {job_id}: Silence detection completed successfully")
+ return silence_intervals, "/v1/media/silence", 200
+
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error during silence detection process - {str(e)}")
+ return str(e), "/v1/media/silence", 500
\ No newline at end of file
diff --git a/routes/v1/s3/upload.py b/routes/v1/s3/upload.py
new file mode 100644
index 0000000000000000000000000000000000000000..8d4a4369e669b26e3abd651800025b9ebf36a648
--- /dev/null
+++ b/routes/v1/s3/upload.py
@@ -0,0 +1,61 @@
+# 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
+from services.authentication import authenticate
+from app_utils import validate_payload, queue_task_wrapper
+from services.v1.s3.upload import stream_upload_to_s3
+import os
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+v1_s3_upload_bp = Blueprint('v1_s3_upload', __name__)
+
+@v1_s3_upload_bp.route('/v1/s3/upload', methods=['POST'])
+@authenticate
+@validate_payload({
+ "type": "object",
+ "properties": {
+ "file_url": {"type": "string", "format": "uri"},
+ "filename": {"type": "string"},
+ "public": {"type": "boolean"},
+ "download_headers": {"type": "object"}
+ },
+ "required": ["file_url"]
+})
+@queue_task_wrapper(bypass_queue=False)
+def s3_upload_endpoint(job_id, data):
+ try:
+ file_url = data.get('file_url')
+ filename = data.get('filename') # Optional, will default to original filename if not provided
+ make_public = data.get('public', False) # Default to private
+ download_headers = data.get('download_headers') # Optional headers for authentication
+
+ logger.info(f"Job {job_id}: Starting S3 streaming upload from {file_url}")
+
+ # Call the service function to handle the upload
+ result = stream_upload_to_s3(file_url, filename, make_public, download_headers)
+
+ logger.info(f"Job {job_id}: Successfully uploaded to S3")
+
+ return result, "/v1/s3/upload", 200
+
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error streaming upload to S3 - {str(e)}")
+ return str(e), "/v1/s3/upload", 500
\ No newline at end of file
diff --git a/routes/v1/toolkit/authenticate.py b/routes/v1/toolkit/authenticate.py
new file mode 100644
index 0000000000000000000000000000000000000000..b38533437fee379c000de8c3657e5120258f63db
--- /dev/null
+++ b/routes/v1/toolkit/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
+
+v1_toolkit_auth_bp = Blueprint('v1_toolkit_auth', __name__)
+
+API_KEY = os.environ.get('API_KEY')
+
+@v1_toolkit_auth_bp.route('/v1/toolkit/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
diff --git a/routes/v1/toolkit/job_status.py b/routes/v1/toolkit/job_status.py
new file mode 100644
index 0000000000000000000000000000000000000000..aebf7ec92b17cd51e80bcd65f80db5f24a5949ec
--- /dev/null
+++ b/routes/v1/toolkit/job_status.py
@@ -0,0 +1,65 @@
+# 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 json
+import logging
+from flask import Blueprint, request
+from config import LOCAL_STORAGE_PATH
+from services.authentication import authenticate
+from app_utils import queue_task_wrapper, validate_payload
+
+v1_toolkit_job_status_bp = Blueprint('v1_toolkit_job_status', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_toolkit_job_status_bp.route('/v1/toolkit/job/status', methods=['POST'])
+@authenticate
+@validate_payload({
+ "type": "object",
+ "properties": {
+ "job_id": {
+ "type": "string"
+ }
+ },
+ "required": ["job_id"],
+})
+@queue_task_wrapper(bypass_queue=True)
+def get_job_status(job_id, data):
+
+ get_job_id = data.get('job_id')
+
+ logger.info(f"Retrieving status for job {get_job_id}")
+
+ try:
+ # Construct the path to the job status file
+ job_file_path = os.path.join(LOCAL_STORAGE_PATH, 'jobs', f"{get_job_id}.json")
+
+ # Check if the job file exists
+ if not os.path.exists(job_file_path):
+ return {"error": "Job not found", "job_id": get_job_id}, endpoint, 404
+
+ # Read the job status file
+ with open(job_file_path, 'r') as file:
+ job_status = json.load(file)
+
+ # Return the job status file content directly
+ return job_status, "/v1/toolkit/job/status", 200
+
+ except Exception as e:
+ logger.error(f"Error retrieving status for job {get_job_id}: {str(e)}")
+ return {"error": f"Failed to retrieve job status: {str(e)}"}, endpoint, 500
\ No newline at end of file
diff --git a/routes/v1/toolkit/jobs_status.py b/routes/v1/toolkit/jobs_status.py
new file mode 100644
index 0000000000000000000000000000000000000000..75ef18eac533083061ffe6acc4b007f5fe3ede74
--- /dev/null
+++ b/routes/v1/toolkit/jobs_status.py
@@ -0,0 +1,89 @@
+# 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 json
+import logging
+import time
+from flask import Blueprint, request
+from config import LOCAL_STORAGE_PATH
+from services.authentication import authenticate
+from app_utils import queue_task_wrapper, validate_payload
+
+v1_toolkit_jobs_status_bp = Blueprint('v1_toolkit_jobs_status', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_toolkit_jobs_status_bp.route('/v1/toolkit/jobs/status', methods=['POST'])
+@authenticate
+@queue_task_wrapper(bypass_queue=True)
+def get_all_jobs_status(job_id, data):
+ """
+ Get the status of all jobs within a specified time range
+
+ Args:
+ job_id (str): Job ID assigned by queue_task_wrapper (unused)
+ data (dict): Request data containing optional since_seconds parameter
+
+ Returns:
+ Tuple of (jobs_status_data, endpoint_string, status_code)
+ """
+ logger.info("Retrieving status for all jobs")
+ endpoint = "/v1/toolkit/jobs/status"
+
+ try:
+ # Get time range parameter (default to 600 seconds/10 minutes if not provided)
+ since_seconds = 600
+ if data and "since_seconds" in data:
+ since_seconds = data.get("since_seconds")
+
+ cutoff_time = time.time() - since_seconds
+
+ # Construct the path to the jobs directory
+ jobs_dir = os.path.join(LOCAL_STORAGE_PATH, 'jobs')
+
+ # Check if the jobs directory exists
+ if not os.path.exists(jobs_dir):
+ return {"error": "Jobs directory not found"}, endpoint, 404
+
+ # Dictionary to store job statuses
+ jobs_status = {}
+
+ # Iterate through job files in the directory
+ for filename in os.listdir(jobs_dir):
+ if filename.endswith('.json'):
+ job_file_path = os.path.join(jobs_dir, filename)
+ file_mod_time = os.path.getmtime(job_file_path)
+
+ # Check if the file was modified within the time range
+ if file_mod_time >= cutoff_time:
+ job_id = filename.split('.')[0] # Remove .json extension to get job_id
+
+ # Read the job status file
+ with open(job_file_path, 'r') as file:
+ job_data = json.load(file)
+
+ # Only include the job_status field, not the response
+ if "job_status" in job_data:
+ jobs_status[job_id] = job_data["job_status"]
+
+ # Return the job statuses
+ return jobs_status, endpoint, 200
+
+ except Exception as e:
+ logger.error(f"Error retrieving status for jobs: {str(e)}")
+ return {"error": f"Failed to retrieve job statuses: {str(e)}"}, endpoint, 500
\ No newline at end of file
diff --git a/routes/v1/toolkit/test.py b/routes/v1/toolkit/test.py
new file mode 100644
index 0000000000000000000000000000000000000000..1442b676c3a387ee554112897abc716af5ef7285
--- /dev/null
+++ b/routes/v1/toolkit/test.py
@@ -0,0 +1,52 @@
+# 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
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+from app_utils import queue_task_wrapper
+from config import LOCAL_STORAGE_PATH
+
+v1_toolkit_test_bp = Blueprint('v1_toolkit_test', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_toolkit_test_bp.route('/v1/toolkit/test', methods=['GET'])
+@authenticate
+@queue_task_wrapper(bypass_queue=True)
+def test_api(job_id, data):
+ logger.info(f"Job {job_id}: Testing NCA Toolkit API setup")
+
+ try:
+ # Create test file
+ test_filename = os.path.join(LOCAL_STORAGE_PATH, "success.txt")
+ with open(test_filename, 'w') as f:
+ f.write("You have successfully installed the NCA Toolkit API, great job!")
+
+ # Upload file to cloud storage
+ upload_url = upload_file(test_filename)
+
+ # Clean up local file
+ os.remove(test_filename)
+
+ return upload_url, "/v1/toolkit/test", 200
+
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error testing API setup - {str(e)}")
+ return str(e), "/v1/toolkit/test", 500
\ No newline at end of file
diff --git a/routes/v1/video/caption_video.py b/routes/v1/video/caption_video.py
new file mode 100644
index 0000000000000000000000000000000000000000..599b9c77e907ba2019a171c412c3d8ee93980e92
--- /dev/null
+++ b/routes/v1/video/caption_video.py
@@ -0,0 +1,187 @@
+# 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.ass_toolkit import generate_ass_captions_v1
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+import os
+import requests # Ensure requests is imported for webhook handling
+
+v1_video_caption_bp = Blueprint('v1_video/caption', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_video_caption_bp.route('/v1/video/caption', methods=['POST'])
+@authenticate
+@validate_payload({
+ "type": "object",
+ "properties": {
+ "video_url": {"type": "string", "format": "uri"},
+ "captions": {"type": "string"},
+ "settings": {
+ "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", "karaoke", "highlight", "underline", "word_by_word"]
+ },
+ "outline_width": {"type": "integer"},
+ "spacing": {"type": "integer"},
+ "angle": {"type": "integer"},
+ "shadow_offset": {"type": "integer"}
+ },
+ "additionalProperties": False
+ },
+ "replace": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "find": {"type": "string"},
+ "replace": {"type": "string"}
+ },
+ "required": ["find", "replace"]
+ }
+ },
+ "exclude_time_ranges": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "start": { "type": "string" },
+ "end": { "type": "string" }
+ },
+ "required": ["start", "end"],
+ "additionalProperties": False
+ }
+ },
+ "webhook_url": {"type": "string", "format": "uri"},
+ "id": {"type": "string"},
+ "language": {"type": "string"}
+ },
+ "required": ["video_url"],
+ "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def caption_video_v1(job_id, data):
+ video_url = data['video_url']
+ captions = data.get('captions')
+ settings = data.get('settings', {})
+ replace = data.get('replace', [])
+ exclude_time_ranges = data.get('exclude_time_ranges', [])
+ webhook_url = data.get('webhook_url')
+ id = data.get('id')
+ language = data.get('language', 'auto')
+
+ logger.info(f"Job {job_id}: Received v1 captioning request for {video_url}")
+ logger.info(f"Job {job_id}: Settings received: {settings}")
+ logger.info(f"Job {job_id}: Replace rules received: {replace}")
+ logger.info(f"Job {job_id}: Exclude time ranges received: {exclude_time_ranges}")
+
+ try:
+ # Do NOT combine position and alignment. Keep them separate.
+ # Just pass settings directly to process_captioning_v1.
+ # This ensures position and alignment remain independent keys.
+
+ # Process video with the enhanced v1 service
+ output = generate_ass_captions_v1(video_url, captions, settings, replace, exclude_time_ranges, job_id, language)
+
+ if isinstance(output, dict) and 'error' in output:
+ # Check if this is a font-related error by checking for 'available_fonts' key
+ if 'available_fonts' in output:
+ # Font error scenario
+ return {"error": output['error'], "available_fonts": output['available_fonts']}, "/v1/video/caption", 400
+ else:
+ # Non-font error scenario, do not return available_fonts
+ return {"error": output['error']}, "/v1/video/caption", 400
+
+ # If processing was successful, output is the ASS file path
+ ass_path = output
+ logger.info(f"Job {job_id}: ASS file generated at {ass_path}")
+
+ # Prepare output filename and path for the rendered video
+ output_filename = f"{job_id}_captioned.mp4"
+ output_path = os.path.join(os.path.dirname(ass_path), output_filename)
+
+ # Download the video (if not already local)
+ video_path = None
+ try:
+ from services.file_management import download_file
+ from config import LOCAL_STORAGE_PATH
+ video_path = download_file(video_url, LOCAL_STORAGE_PATH)
+ logger.info(f"Job {job_id}: Video downloaded to {video_path}")
+ except Exception as e:
+ logger.error(f"Job {job_id}: Video download error: {str(e)}")
+ return {"error": str(e)}, "/v1/video/caption", 500
+
+ # Render the video with subtitles using FFmpeg
+ try:
+ import ffmpeg
+ ffmpeg.input(video_path).output(
+ output_path,
+ vf=f"subtitles='{ass_path}'",
+ acodec='copy'
+ ).run(overwrite_output=True)
+ logger.info(f"Job {job_id}: FFmpeg processing completed. Output saved to {output_path}")
+ except Exception as e:
+ logger.error(f"Job {job_id}: FFmpeg error: {str(e)}")
+ return {"error": f"FFmpeg error: {str(e)}"}, "/v1/video/caption", 500
+
+ # Clean up the ASS file after use
+ os.remove(ass_path)
+
+ # Upload the captioned video
+ cloud_url = upload_file(output_path)
+ logger.info(f"Job {job_id}: Captioned video uploaded to cloud storage: {cloud_url}")
+
+ # Clean up the output file after upload
+ os.remove(output_path)
+ logger.info(f"Job {job_id}: Cleaned up local output file")
+
+ return cloud_url, "/v1/video/caption", 200
+
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error during captioning process - {str(e)}", exc_info=True)
+ return {"error": str(e)}, "/v1/video/caption", 500
diff --git a/routes/v1/video/concatenate.py b/routes/v1/video/concatenate.py
new file mode 100644
index 0000000000000000000000000000000000000000..4d542287691277e2311dc3a609e4369e7122bb7b
--- /dev/null
+++ b/routes/v1/video/concatenate.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.v1.video.concatenate import process_video_concatenate
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+
+v1_video_concatenate_bp = Blueprint('v1_video_concatenate', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_video_concatenate_bp.route('/v1/video/concatenate', 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_concatenate(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, "/v1/video/concatenate", 200
+
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error during video combination process - {str(e)}")
+ return str(e), "/v1/video/concatenate", 500
\ No newline at end of file
diff --git a/routes/v1/video/cut.py b/routes/v1/video/cut.py
new file mode 100644
index 0000000000000000000000000000000000000000..343b4bfe68ba67224476629ad86d4b1d51ef308a
--- /dev/null
+++ b/routes/v1/video/cut.py
@@ -0,0 +1,102 @@
+# 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.video.cut import cut_media
+from services.authentication import authenticate
+
+v1_video_cut_bp = Blueprint('v1_video_cut', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_video_cut_bp.route('/v1/video/cut', methods=['POST'])
+@authenticate
+@validate_payload({
+ "type": "object",
+ "properties": {
+ "video_url": {"type": "string", "format": "uri"},
+ "cuts": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "start": {"type": "string"},
+ "end": {"type": "string"}
+ },
+ "required": ["start", "end"],
+ "additionalProperties": False
+ },
+ "minItems": 1
+ },
+ "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": ["video_url", "cuts"],
+ "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def video_cut(job_id, data):
+ """Cut specified segments from a video file with optional encoding settings."""
+ video_url = data['video_url']
+ cuts = data['cuts']
+
+ # Extract encoding settings with defaults
+ 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')
+
+ logger.info(f"Job {job_id}: Received video cut request for {video_url}")
+
+ try:
+ # Process the video file and get local file paths
+ output_filename, input_filename = cut_media(
+ video_url=video_url,
+ cuts=cuts,
+ job_id=job_id,
+ video_codec=video_codec,
+ video_preset=video_preset,
+ video_crf=video_crf,
+ audio_codec=audio_codec,
+ audio_bitrate=audio_bitrate
+ )
+
+ # Upload the processed file to cloud storage
+ from services.cloud_storage import upload_file
+ cloud_url = upload_file(output_filename)
+ logger.info(f"Job {job_id}: Uploaded output to cloud: {cloud_url}")
+
+ # Clean up temporary files
+ import os
+ os.remove(input_filename)
+ os.remove(output_filename)
+ logger.info(f"Job {job_id}: Removed temporary files")
+
+ logger.info(f"Job {job_id}: Video cut operation completed successfully")
+ return cloud_url, "/v1/video/cut", 200
+
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error during video cut process - {str(e)}")
+ return str(e), "/v1/video/cut", 500
\ No newline at end of file
diff --git a/routes/v1/video/split.py b/routes/v1/video/split.py
new file mode 100644
index 0000000000000000000000000000000000000000..7417497ef8b6f6ddc30efb6d9912bc9f06281d3b
--- /dev/null
+++ b/routes/v1/video/split.py
@@ -0,0 +1,115 @@
+# 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.video.split import split_video
+from services.authentication import authenticate
+
+v1_video_split_bp = Blueprint('v1_video_split', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_video_split_bp.route('/v1/video/split', methods=['POST'])
+@authenticate
+@validate_payload({
+ "type": "object",
+ "properties": {
+ "video_url": {"type": "string", "format": "uri"},
+ "splits": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "start": {"type": "string"},
+ "end": {"type": "string"}
+ },
+ "required": ["start", "end"],
+ "additionalProperties": False
+ },
+ "minItems": 1
+ },
+ "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": ["video_url", "splits"],
+ "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def video_split(job_id, data):
+ """Split a video file into multiple segments with optional encoding settings."""
+ video_url = data['video_url']
+ splits = data['splits']
+
+ # Extract encoding settings with defaults
+ 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')
+
+ logger.info(f"Job {job_id}: Received video split request for {video_url}")
+
+ try:
+ # Process the video file and get list of output files
+ output_files, input_filename = split_video(
+ video_url=video_url,
+ splits=splits,
+ job_id=job_id,
+ video_codec=video_codec,
+ video_preset=video_preset,
+ video_crf=video_crf,
+ audio_codec=audio_codec,
+ audio_bitrate=audio_bitrate
+ )
+
+ # Upload all output files to cloud storage
+ from services.cloud_storage import upload_file
+ result_files = []
+
+ for i, output_file in enumerate(output_files):
+ cloud_url = upload_file(output_file)
+ result_files.append({
+ "file_url": cloud_url,
+ "start": splits[i]["start"],
+ "end": splits[i]["end"]
+ })
+ # Remove the local file after upload
+ import os
+ os.remove(output_file)
+ logger.info(f"Job {job_id}: Uploaded and removed split file {i+1}")
+
+ # Clean up input file
+ import os
+ os.remove(input_filename)
+ logger.info(f"Job {job_id}: Removed input file")
+
+ # Prepare the response with only file URLs
+ response = [{"file_url": item["file_url"]} for item in result_files]
+
+ logger.info(f"Job {job_id}: Video split operation completed successfully")
+ return response, "/v1/video/split", 200
+
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error during video split process - {str(e)}")
+ return str(e), "/v1/video/split", 500
\ No newline at end of file
diff --git a/routes/v1/video/thumbnail.py b/routes/v1/video/thumbnail.py
new file mode 100644
index 0000000000000000000000000000000000000000..08fe587d53b64553b0843e4eea880b9476de22c5
--- /dev/null
+++ b/routes/v1/video/thumbnail.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.
+
+
+
+from flask import Blueprint, jsonify
+from app_utils import *
+import logging
+from services.v1.video.thumbnail import extract_thumbnail
+from services.authentication import authenticate
+from services.cloud_storage import upload_file
+
+v1_video_thumbnail_bp = Blueprint('v1_video_thumbnail', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_video_thumbnail_bp.route('/v1/video/thumbnail', methods=['POST'])
+@authenticate
+@validate_payload({
+ "type": "object",
+ "properties": {
+ "video_url": {"type": "string", "format": "uri"},
+ "second": {"type": "number", "minimum": 0},
+ "webhook_url": {"type": "string", "format": "uri"},
+ "id": {"type": "string"}
+ },
+ "required": ["video_url"],
+ "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def generate_thumbnail(job_id, data):
+ video_url = data.get('video_url')
+ second = data.get('second', 0) # Default to 0 if not provided
+ webhook_url = data.get('webhook_url')
+
+ logger.info(f"Job {job_id}: Received thumbnail extraction request for {video_url} at {second} seconds")
+
+ try:
+ # Process thumbnail extraction
+ thumbnail_path = extract_thumbnail(video_url, job_id, second)
+
+ # Upload the thumbnail to cloud storage
+ file_url = upload_file(thumbnail_path)
+
+ logger.info(f"Job {job_id}: Thumbnail uploaded to cloud storage at {file_url}")
+
+ # Return the URL of the uploaded thumbnail
+ return file_url, "/v1/video/thumbnail", 200
+
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error during thumbnail extraction - {str(e)}")
+ return str(e), "/v1/video/thumbnail", 500
diff --git a/routes/v1/video/trim.py b/routes/v1/video/trim.py
new file mode 100644
index 0000000000000000000000000000000000000000..10f039456547952b29a8bcad4e7e574d3a8ab38f
--- /dev/null
+++ b/routes/v1/video/trim.py
@@ -0,0 +1,93 @@
+# 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.video.trim import trim_video
+from services.authentication import authenticate
+
+v1_video_trim_bp = Blueprint('v1_video_trim', __name__)
+logger = logging.getLogger(__name__)
+
+@v1_video_trim_bp.route('/v1/video/trim', methods=['POST'])
+@authenticate
+@validate_payload({
+ "type": "object",
+ "properties": {
+ "video_url": {"type": "string", "format": "uri"},
+ "start": {"type": "string"},
+ "end": {"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": ["video_url"],
+ "additionalProperties": False
+})
+@queue_task_wrapper(bypass_queue=False)
+def video_trim(job_id, data):
+ """Trim a video by removing specified portions from the beginning and/or end with optional encoding settings."""
+ video_url = data['video_url']
+ start = data.get('start')
+ end = data.get('end')
+
+ # Extract encoding settings with defaults
+ 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')
+
+ logger.info(f"Job {job_id}: Received video trim request for {video_url}")
+
+ try:
+ # Process the video file and get local file paths
+ output_filename, input_filename = trim_video(
+ video_url=video_url,
+ start=start,
+ end=end,
+ job_id=job_id,
+ video_codec=video_codec,
+ video_preset=video_preset,
+ video_crf=video_crf,
+ audio_codec=audio_codec,
+ audio_bitrate=audio_bitrate
+ )
+
+ # Upload the processed file to cloud storage
+ from services.cloud_storage import upload_file
+ cloud_url = upload_file(output_filename)
+ logger.info(f"Job {job_id}: Uploaded output to cloud: {cloud_url}")
+
+ # Clean up temporary files
+ import os
+ os.remove(input_filename)
+ os.remove(output_filename)
+ logger.info(f"Job {job_id}: Removed temporary files")
+
+ logger.info(f"Job {job_id}: Video trim operation completed successfully")
+ return cloud_url, "/v1/video/trim", 200
+
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error during video trim process - {str(e)}")
+ return str(e), "/v1/video/trim", 500
\ No newline at end of file
diff --git a/services/ass_toolkit.py b/services/ass_toolkit.py
new file mode 100644
index 0000000000000000000000000000000000000000..9b88376df74c2bb19e38b46bf0220a556cac9e19
--- /dev/null
+++ b/services/ass_toolkit.py
@@ -0,0 +1,879 @@
+# 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 ffmpeg
+import logging
+import subprocess
+import whisper
+from datetime import timedelta
+import srt
+import re
+from services.file_management import download_file
+from services.cloud_storage import upload_file # Ensure this import is present
+import requests # Ensure requests is imported for webhook handling
+from urllib.parse import urlparse
+from config import LOCAL_STORAGE_PATH
+
+# Initialize logger
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+if not logger.hasHandlers():
+ handler = logging.StreamHandler()
+ formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+ handler.setFormatter(formatter)
+ logger.addHandler(handler)
+
+POSITION_ALIGNMENT_MAP = {
+ "bottom_left": 1,
+ "bottom_center": 2,
+ "bottom_right": 3,
+ "middle_left": 4,
+ "middle_center": 5,
+ "middle_right": 6,
+ "top_left": 7,
+ "top_center": 8,
+ "top_right": 9
+}
+
+def rgb_to_ass_color(rgb_color):
+ """Convert RGB hex to ASS (&HAABBGGRR)."""
+ if isinstance(rgb_color, str):
+ rgb_color = rgb_color.lstrip('#')
+ if len(rgb_color) == 6:
+ r = int(rgb_color[0:2], 16)
+ g = int(rgb_color[2:4], 16)
+ b = int(rgb_color[4:6], 16)
+ return f"&H00{b:02X}{g:02X}{r:02X}"
+ return "&H00FFFFFF"
+
+def generate_transcription(video_path, language='auto'):
+ try:
+ model = whisper.load_model("base")
+ transcription_options = {
+ 'word_timestamps': True,
+ 'verbose': True,
+ }
+ if language != 'auto':
+ transcription_options['language'] = language
+ result = model.transcribe(video_path, **transcription_options)
+ logger.info(f"Transcription generated successfully for video: {video_path}")
+ return result
+ except Exception as e:
+ logger.error(f"Error in transcription: {str(e)}")
+ raise
+
+def get_video_resolution(video_path):
+ try:
+ probe = ffmpeg.probe(video_path)
+ video_streams = [s for s in probe['streams'] if s['codec_type'] == 'video']
+ if video_streams:
+ width = int(video_streams[0]['width'])
+ height = int(video_streams[0]['height'])
+ logger.info(f"Video resolution determined: {width}x{height}")
+ return width, height
+ else:
+ logger.warning(f"No video streams found for {video_path}. Using default resolution 384x288.")
+ return 384, 288
+ except Exception as e:
+ logger.error(f"Error getting video resolution: {str(e)}. Using default resolution 384x288.")
+ return 384, 288
+
+def get_available_fonts():
+ """Get the list of available fonts on the system."""
+ try:
+ import matplotlib.font_manager as fm
+ except ImportError:
+ logger.error("matplotlib not installed. Install via 'pip install matplotlib'.")
+ return []
+ font_list = fm.findSystemFonts(fontpaths=None, fontext='ttf')
+ font_names = set()
+ for font in font_list:
+ try:
+ font_prop = fm.FontProperties(fname=font)
+ font_name = font_prop.get_name()
+ font_names.add(font_name)
+ except Exception:
+ continue
+ logger.info(f"Available fonts retrieved: {font_names}")
+ return list(font_names)
+
+def format_ass_time(seconds):
+ """Convert float seconds to ASS time format H:MM:SS.cc"""
+ hours = int(seconds // 3600)
+ minutes = int((seconds % 3600) // 60)
+ secs = int(seconds % 60)
+ centiseconds = int(round((seconds - int(seconds)) * 100))
+ return f"{hours}:{minutes:02}:{secs:02}.{centiseconds:02}"
+
+def process_subtitle_text(text, replace_dict, all_caps, max_words_per_line):
+ """Apply text transformations: replacements, all caps, and optional line splitting."""
+ for old_word, new_word in replace_dict.items():
+ text = re.sub(re.escape(old_word), new_word, text, flags=re.IGNORECASE)
+ if all_caps:
+ text = text.upper()
+ if max_words_per_line > 0:
+ words = text.split()
+ lines = [' '.join(words[i:i+max_words_per_line]) for i in range(0, len(words), max_words_per_line)]
+ text = '\\N'.join(lines)
+ return text
+
+def srt_to_transcription_result(srt_content):
+ """Convert SRT content into a transcription-like structure for uniform processing."""
+ subtitles = list(srt.parse(srt_content))
+ segments = []
+ for sub in subtitles:
+ segments.append({
+ 'start': sub.start.total_seconds(),
+ 'end': sub.end.total_seconds(),
+ 'text': sub.content.strip(),
+ 'words': [] # SRT does not provide word-level timestamps
+ })
+ logger.info("Converted SRT content to transcription result.")
+ return {'segments': segments}
+
+def split_lines(text, max_words_per_line):
+ """Split text into multiple lines if max_words_per_line > 0."""
+ if max_words_per_line <= 0:
+ return [text]
+ words = text.split()
+ lines = [' '.join(words[i:i+max_words_per_line]) for i in range(0, len(words), max_words_per_line)]
+ return lines
+
+def is_url(string):
+ """Check if the given string is a valid HTTP/HTTPS URL."""
+ try:
+ result = urlparse(string)
+ return result.scheme in ('http', 'https')
+ except:
+ return False
+
+def download_captions(captions_url):
+ """Download captions from the given URL."""
+ try:
+ logger.info(f"Downloading captions from URL: {captions_url}")
+ response = requests.get(captions_url)
+ response.raise_for_status()
+ logger.info("Captions downloaded successfully.")
+ return response.text
+ except Exception as e:
+ logger.error(f"Error downloading captions: {str(e)}")
+ raise
+
+def determine_alignment_code(position_str, alignment_str, x, y, video_width, video_height):
+ """
+ Determine the final \an alignment code and (x,y) position based on:
+ - x,y (if provided)
+ - position_str (one of top_left, top_center, ...)
+ - alignment_str (left, center, right)
+ - If x,y not provided, divide the video into a 3x3 grid and position accordingly.
+ """
+ logger.info(f"[determine_alignment_code] Inputs: position_str={position_str}, alignment_str={alignment_str}, x={x}, y={y}, video_width={video_width}, video_height={video_height}")
+
+ horizontal_map = {
+ 'left': 1,
+ 'center': 2,
+ 'right': 3
+ }
+
+ # If x and y are provided, use them directly and set \an based on alignment_str
+ if x is not None and y is not None:
+ logger.info("[determine_alignment_code] x and y provided, ignoring position and alignment for grid.")
+ vertical_code = 4 # Middle row
+ horiz_code = horizontal_map.get(alignment_str, 2) # Default to center
+ an_code = vertical_code + (horiz_code - 1)
+ logger.info(f"[determine_alignment_code] Using provided x,y. an_code={an_code}")
+ return an_code, True, x, y
+
+ # No x,y provided: determine position and alignment based on grid
+ pos_lower = position_str.lower()
+ if 'top' in pos_lower:
+ vertical_base = 7 # Top row an codes start at 7
+ vertical_center = video_height / 6
+ elif 'middle' in pos_lower:
+ vertical_base = 4 # Middle row an codes start at 4
+ vertical_center = video_height / 2
+ else:
+ vertical_base = 1 # Bottom row an codes start at 1
+ vertical_center = (5 * video_height) / 6
+
+ if 'left' in pos_lower:
+ left_boundary = 0
+ right_boundary = video_width / 3
+ center_line = video_width / 6
+ elif 'right' in pos_lower:
+ left_boundary = (2 * video_width) / 3
+ right_boundary = video_width
+ center_line = (5 * video_width) / 6
+ else:
+ # Center column
+ left_boundary = video_width / 3
+ right_boundary = (2 * video_width) / 3
+ center_line = video_width / 2
+
+ # Alignment affects horizontal position within the cell
+ if alignment_str == 'left':
+ final_x = left_boundary
+ horiz_code = 1
+ elif alignment_str == 'right':
+ final_x = right_boundary
+ horiz_code = 3
+ else:
+ final_x = center_line
+ horiz_code = 2
+
+ final_y = vertical_center
+ an_code = vertical_base + (horiz_code - 1)
+
+ logger.info(f"[determine_alignment_code] Computed final_x={final_x}, final_y={final_y}, an_code={an_code}")
+ return an_code, True, int(final_x), int(final_y)
+
+def create_style_line(style_options, video_resolution):
+ """
+ Create the style line for ASS subtitles.
+ """
+ font_family = style_options.get('font_family', 'Arial')
+ available_fonts = get_available_fonts()
+ if font_family not in available_fonts:
+ logger.warning(f"Font '{font_family}' not found.")
+ return {'error': f"Font '{font_family}' not available.", 'available_fonts': available_fonts}
+
+ line_color = rgb_to_ass_color(style_options.get('line_color', '#FFFFFF'))
+ secondary_color = line_color
+ outline_color = rgb_to_ass_color(style_options.get('outline_color', '#000000'))
+ box_color = rgb_to_ass_color(style_options.get('box_color', '#000000'))
+
+ font_size = style_options.get('font_size', int(video_resolution[1] * 0.05))
+ bold = '1' if style_options.get('bold', False) else '0'
+ italic = '1' if style_options.get('italic', False) else '0'
+ underline = '1' if style_options.get('underline', False) else '0'
+ strikeout = '1' if style_options.get('strikeout', False) else '0'
+ scale_x = style_options.get('scale_x', '100')
+ scale_y = style_options.get('scale_y', '100')
+ spacing = style_options.get('spacing', '0')
+ angle = style_options.get('angle', '0')
+ border_style = style_options.get('border_style', '1')
+ outline_width = style_options.get('outline_width', '2')
+ shadow_offset = style_options.get('shadow_offset', '0')
+
+ margin_l = style_options.get('margin_l', '20')
+ margin_r = style_options.get('margin_r', '20')
+ margin_v = style_options.get('margin_v', '20')
+
+ # Default alignment in style (we override per event)
+ alignment = 5
+
+ style_line = (
+ f"Style: Default,{font_family},{font_size},{line_color},{secondary_color},"
+ f"{outline_color},{box_color},{bold},{italic},{underline},{strikeout},"
+ f"{scale_x},{scale_y},{spacing},{angle},{border_style},{outline_width},"
+ f"{shadow_offset},{alignment},{margin_l},{margin_r},{margin_v},0"
+ )
+ logger.info(f"Created ASS style line: {style_line}")
+ return style_line
+
+def generate_ass_header(style_options, video_resolution):
+ """
+ Generate the ASS file header with the Default style.
+ """
+ ass_header = f"""[Script Info]
+ScriptType: v4.00+
+PlayResX: {video_resolution[0]}
+PlayResY: {video_resolution[1]}
+ScaledBorderAndShadow: yes
+
+[V4+ Styles]
+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
+"""
+ style_line = create_style_line(style_options, video_resolution)
+ if isinstance(style_line, dict) and 'error' in style_line:
+ # Font-related error
+ return style_line
+
+ ass_header += style_line + "\n\n[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\n"
+ logger.info("Generated ASS header.")
+ return ass_header
+
+### STYLE HANDLERS ###
+
+def handle_classic(transcription_result, style_options, replace_dict, video_resolution):
+ """
+ Classic style handler: Centers the text based on position and alignment.
+ """
+ max_words_per_line = int(style_options.get('max_words_per_line', 0))
+ all_caps = style_options.get('all_caps', False)
+ if style_options['font_size'] is None:
+ style_options['font_size'] = int(video_resolution[1] * 0.05)
+
+ position_str = style_options.get('position', 'middle_center')
+ alignment_str = style_options.get('alignment', 'center')
+ x = style_options.get('x')
+ y = style_options.get('y')
+
+ an_code, use_pos, final_x, final_y = determine_alignment_code(
+ position_str, alignment_str, x, y,
+ video_width=video_resolution[0],
+ video_height=video_resolution[1]
+ )
+
+ logger.info(f"[Classic] position={position_str}, alignment={alignment_str}, x={final_x}, y={final_y}, an_code={an_code}")
+
+ events = []
+ for segment in transcription_result['segments']:
+ text = segment['text'].strip().replace('\n', ' ')
+ lines = split_lines(text, max_words_per_line)
+ processed_text = '\\N'.join(process_subtitle_text(line, replace_dict, all_caps, 0) for line in lines)
+ start_time = format_ass_time(segment['start'])
+ end_time = format_ass_time(segment['end'])
+ position_tag = f"{{\\an{an_code}\\pos({final_x},{final_y})}}"
+ events.append(f"Dialogue: 0,{start_time},{end_time},Default,,0,0,0,,{position_tag}{processed_text}")
+ logger.info(f"Handled {len(events)} dialogues in classic style.")
+ return "\n".join(events)
+
+def handle_karaoke(transcription_result, style_options, replace_dict, video_resolution):
+ """
+ Karaoke style handler: Highlights words as they are spoken.
+ """
+ max_words_per_line = int(style_options.get('max_words_per_line', 0))
+ all_caps = style_options.get('all_caps', False)
+ if style_options['font_size'] is None:
+ style_options['font_size'] = int(video_resolution[1] * 0.05)
+
+ position_str = style_options.get('position', 'middle_center')
+ alignment_str = style_options.get('alignment', 'center')
+ x = style_options.get('x')
+ y = style_options.get('y')
+
+ an_code, use_pos, final_x, final_y = determine_alignment_code(
+ position_str, alignment_str, x, y,
+ video_width=video_resolution[0],
+ video_height=video_resolution[1]
+ )
+ word_color = rgb_to_ass_color(style_options.get('word_color', '#FFFF00'))
+
+ logger.info(f"[Karaoke] position={position_str}, alignment={alignment_str}, x={final_x}, y={final_y}, an_code={an_code}")
+
+ events = []
+ for segment in transcription_result['segments']:
+ words = segment.get('words', [])
+ if not words:
+ continue
+
+ if max_words_per_line > 0:
+ lines_content = []
+ current_line = []
+ current_line_words = 0
+ for w_info in words:
+ w = process_subtitle_text(w_info.get('word', ''), replace_dict, all_caps, 0)
+ duration_cs = int(round((w_info['end'] - w_info['start']) * 100))
+ highlighted_word = f"{{\\k{duration_cs}}}{w} "
+ current_line.append(highlighted_word)
+ current_line_words += 1
+ if current_line_words >= max_words_per_line:
+ lines_content.append(''.join(current_line).strip())
+ current_line = []
+ current_line_words = 0
+ if current_line:
+ lines_content.append(''.join(current_line).strip())
+ else:
+ line_content = []
+ for w_info in words:
+ w = process_subtitle_text(w_info.get('word', ''), replace_dict, all_caps, 0)
+ duration_cs = int(round((w_info['end'] - w_info['start']) * 100))
+ highlighted_word = f"{{\\k{duration_cs}}}{w} "
+ line_content.append(highlighted_word)
+ lines_content = [''.join(line_content).strip()]
+
+ dialogue_text = '\\N'.join(lines_content)
+ start_time = format_ass_time(words[0]['start'])
+ end_time = format_ass_time(words[-1]['end'])
+ position_tag = f"{{\\an{an_code}\\pos({final_x},{final_y})}}"
+ events.append(f"Dialogue: 0,{start_time},{end_time},Default,,0,0,0,,{position_tag}{{\\c{word_color}}}{dialogue_text}")
+ logger.info(f"Handled {len(events)} dialogues in karaoke style.")
+ return "\n".join(events)
+
+def handle_highlight(transcription_result, style_options, replace_dict, video_resolution):
+ """
+ Highlight style handler: Highlights words sequentially.
+ """
+ max_words_per_line = int(style_options.get('max_words_per_line', 0))
+ all_caps = style_options.get('all_caps', False)
+ if style_options['font_size'] is None:
+ style_options['font_size'] = int(video_resolution[1] * 0.05)
+
+ position_str = style_options.get('position', 'middle_center')
+ alignment_str = style_options.get('alignment', 'center')
+ x = style_options.get('x')
+ y = style_options.get('y')
+
+ an_code, use_pos, final_x, final_y = determine_alignment_code(
+ position_str, alignment_str, x, y,
+ video_width=video_resolution[0],
+ video_height=video_resolution[1]
+ )
+
+ word_color = rgb_to_ass_color(style_options.get('word_color', '#FFFF00'))
+ line_color = rgb_to_ass_color(style_options.get('line_color', '#FFFFFF'))
+ events = []
+
+ logger.info(f"[Highlight] position={position_str}, alignment={alignment_str}, x={final_x}, y={final_y}, an_code={an_code}")
+
+ for segment in transcription_result['segments']:
+ words = segment.get('words', [])
+ if not words:
+ continue
+
+ # Process all words in the segment
+ processed_words = []
+ for w_info in words:
+ w = process_subtitle_text(w_info.get('word', ''), replace_dict, all_caps, 0)
+ if w:
+ processed_words.append((w, w_info['start'], w_info['end']))
+
+ if not processed_words:
+ continue
+
+ # Split into lines if max_words_per_line is specified
+ if max_words_per_line > 0:
+ line_sets = [processed_words[i:i+max_words_per_line] for i in range(0, len(processed_words), max_words_per_line)]
+ else:
+ line_sets = [processed_words]
+
+ for line_set in line_sets:
+ # Get the start time of the first word and end time of the last word
+ line_start = line_set[0][1]
+ line_end = line_set[-1][2]
+
+ # Create a persistent line that stays visible during the entire segment
+ base_text = ' '.join(word for word, _, _ in line_set)
+ start_time = format_ass_time(line_start)
+ end_time = format_ass_time(line_end)
+ position_tag = f"{{\\an{an_code}\\pos({final_x},{final_y})}}"
+ events.append(f"Dialogue: 0,{start_time},{end_time},Default,,0,0,0,,{position_tag}{{\\c{line_color}}}{base_text}")
+
+ # Add individual highlighting for each word
+ for idx, (word, w_start, w_end) in enumerate(line_set):
+ # Create the highlighted version of this word within the line
+ highlighted_words = []
+
+ for i, (w, _, _) in enumerate(line_set):
+ if i == idx:
+ # This is the current word - highlight it
+ highlighted_words.append(f"{{\\c{word_color}}}{w}{{\\c{line_color}}}")
+ else:
+ # Add the word without highlighting
+ highlighted_words.append(w)
+
+ highlighted_text = ' '.join(highlighted_words)
+ word_start_time = format_ass_time(w_start)
+ word_end_time = format_ass_time(w_end)
+ events.append(f"Dialogue: 1,{word_start_time},{word_end_time},Default,,0,0,0,,{position_tag}{{\\c{line_color}}}{highlighted_text}")
+
+ logger.info(f"Handled {len(events)} dialogues in highlight style.")
+ return "\n".join(events)
+
+def handle_underline(transcription_result, style_options, replace_dict, video_resolution):
+ """
+ Underline style handler: Underlines the current word.
+ """
+ max_words_per_line = int(style_options.get('max_words_per_line', 0))
+ all_caps = style_options.get('all_caps', False)
+ if style_options['font_size'] is None:
+ style_options['font_size'] = int(video_resolution[1] * 0.05)
+
+ position_str = style_options.get('position', 'middle_center')
+ alignment_str = style_options.get('alignment', 'center')
+ x = style_options.get('x')
+ y = style_options.get('y')
+
+ an_code, use_pos, final_x, final_y = determine_alignment_code(
+ position_str, alignment_str, x, y,
+ video_width=video_resolution[0],
+ video_height=video_resolution[1]
+ )
+ line_color = rgb_to_ass_color(style_options.get('line_color', '#FFFFFF'))
+ events = []
+
+ logger.info(f"[Underline] position={position_str}, alignment={alignment_str}, x={final_x}, y={final_y}, an_code={an_code}")
+
+ for segment in transcription_result['segments']:
+ words = segment.get('words', [])
+ if not words:
+ continue
+ processed_words = []
+ for w_info in words:
+ w = process_subtitle_text(w_info.get('word', ''), replace_dict, all_caps, 0)
+ if w:
+ processed_words.append((w, w_info['start'], w_info['end']))
+
+ if not processed_words:
+ continue
+
+ if max_words_per_line > 0:
+ line_sets = [processed_words[i:i+max_words_per_line] for i in range(0, len(processed_words), max_words_per_line)]
+ else:
+ line_sets = [processed_words]
+
+ for line_set in line_sets:
+ for idx, (word, w_start, w_end) in enumerate(line_set):
+ line_words = []
+ for w_idx, (w_text, _, _) in enumerate(line_set):
+ if w_idx == idx:
+ line_words.append(f"{{\\u1}}{w_text}{{\\u0}}")
+ else:
+ line_words.append(w_text)
+ full_text = ' '.join(line_words)
+ start_time = format_ass_time(w_start)
+ end_time = format_ass_time(w_end)
+ position_tag = f"{{\\an{an_code}\\pos({final_x},{final_y})}}"
+ events.append(f"Dialogue: 0,{start_time},{end_time},Default,,0,0,0,,{position_tag}{{\\c{line_color}}}{full_text}")
+ logger.info(f"Handled {len(events)} dialogues in underline style.")
+ return "\n".join(events)
+
+def handle_word_by_word(transcription_result, style_options, replace_dict, video_resolution):
+ """
+ Word-by-Word style handler: Displays each word individually.
+ """
+ max_words_per_line = int(style_options.get('max_words_per_line', 0))
+ all_caps = style_options.get('all_caps', False)
+ if style_options['font_size'] is None:
+ style_options['font_size'] = int(video_resolution[1] * 0.05)
+
+ position_str = style_options.get('position', 'middle_center')
+ alignment_str = style_options.get('alignment', 'center')
+ x = style_options.get('x')
+ y = style_options.get('y')
+
+ an_code, use_pos, final_x, final_y = determine_alignment_code(
+ position_str, alignment_str, x, y,
+ video_width=video_resolution[0],
+ video_height=video_resolution[1]
+ )
+ word_color = rgb_to_ass_color(style_options.get('word_color', '#FFFF00'))
+ events = []
+
+ logger.info(f"[Word-by-Word] position={position_str}, alignment={alignment_str}, x={final_x}, y={final_y}, an_code={an_code}")
+
+ for segment in transcription_result['segments']:
+ words = segment.get('words', [])
+ if not words:
+ continue
+
+ if max_words_per_line > 0:
+ grouped_words = [words[i:i+max_words_per_line] for i in range(0, len(words), max_words_per_line)]
+ else:
+ grouped_words = [words]
+
+ for word_group in grouped_words:
+ for w_info in word_group:
+ w = process_subtitle_text(w_info.get('word', ''), replace_dict, all_caps, 0)
+ if not w:
+ continue
+ start_time = format_ass_time(w_info['start'])
+ end_time = format_ass_time(w_info['end'])
+ position_tag = f"{{\\an{an_code}\\pos({final_x},{final_y})}}"
+ events.append(f"Dialogue: 0,{start_time},{end_time},Default,,0,0,0,,{position_tag}{{\\c{word_color}}}{w}")
+ logger.info(f"Handled {len(events)} dialogues in word-by-word style.")
+ return "\n".join(events)
+
+STYLE_HANDLERS = {
+ 'classic': handle_classic,
+ 'karaoke': handle_karaoke,
+ 'highlight': handle_highlight,
+ 'underline': handle_underline,
+ 'word_by_word': handle_word_by_word
+}
+
+def srt_to_ass(transcription_result, style_type, settings, replace_dict, video_resolution):
+ """
+ Convert transcription result to ASS based on the specified style.
+ """
+ default_style_settings = {
+ 'line_color': '#FFFFFF',
+ 'word_color': '#FFFF00',
+ 'box_color': '#000000',
+ 'outline_color': '#000000',
+ 'all_caps': False,
+ 'max_words_per_line': 0,
+ 'font_size': None,
+ 'font_family': 'Arial',
+ 'bold': False,
+ 'italic': False,
+ 'underline': False,
+ 'strikeout': False,
+ 'outline_width': 2,
+ 'shadow_offset': 0,
+ 'border_style': 1,
+ 'x': None,
+ 'y': None,
+ 'position': 'middle_center',
+ 'alignment': 'center' # default alignment
+ }
+ style_options = {**default_style_settings, **settings}
+
+ if style_options['font_size'] is None:
+ style_options['font_size'] = int(video_resolution[1] * 0.05)
+
+ ass_header = generate_ass_header(style_options, video_resolution)
+ if isinstance(ass_header, dict) and 'error' in ass_header:
+ # Font-related error
+ return ass_header
+
+ handler = STYLE_HANDLERS.get(style_type.lower())
+ if not handler:
+ logger.warning(f"Unknown style '{style_type}', defaulting to 'classic'.")
+ handler = handle_classic
+
+ dialogue_lines = handler(transcription_result, style_options, replace_dict, video_resolution)
+ logger.info("Converted transcription result to ASS format.")
+ return ass_header + dialogue_lines + "\n"
+
+def process_subtitle_events(transcription_result, style_type, settings, replace_dict, video_resolution):
+ """
+ Process transcription results into ASS subtitle format.
+ """
+ return srt_to_ass(transcription_result, style_type, settings, replace_dict, video_resolution)
+
+def parse_time_string(time_str):
+ """Parse a time string in hh:mm:ss.ms or mm:ss.ms or ss.ms format to seconds (float)."""
+ import re
+ if not isinstance(time_str, str):
+ raise ValueError("Time value must be a string in hh:mm:ss.ms format.")
+ pattern = r"^(?:(\d+):)?(\d{1,2}):(\d{2}(?:\.\d{1,3})?)$"
+ match = re.match(pattern, time_str)
+ if not match:
+ # Try ss.ms only
+ try:
+ return float(time_str)
+ except Exception:
+ raise ValueError(f"Invalid time string: {time_str}")
+ h, m, s = match.groups(default="0")
+ total_seconds = int(h) * 3600 + int(m) * 60 + float(s)
+ return total_seconds
+
+def filter_subtitle_lines(sub_content, exclude_time_ranges, subtitle_type):
+ """
+ Remove subtitle lines/blocks that overlap with exclude_time_ranges.
+ Supports 'ass' and 'srt' subtitle_type.
+ """
+
+ def parse_ass_time(ass_time):
+ try:
+ h, m, rest = ass_time.split(":")
+ s, cs = rest.split(".")
+ return int(h) * 3600 + int(m) * 60 + int(s) + int(cs) / 100
+ except Exception:
+ return 0
+ def parse_time_range(rng):
+ start = parse_time_string(rng['start'])
+ end = parse_time_string(rng['end'])
+ return {'start': start, 'end': end}
+ parsed_ranges = [parse_time_range(rng) for rng in exclude_time_ranges]
+ if not exclude_time_ranges:
+ return sub_content
+ if subtitle_type == 'ass':
+ lines = sub_content.splitlines()
+ filtered_lines = []
+ for line in lines:
+ if line.startswith("Dialogue:"):
+ parts = line.split(",", 10)
+ if len(parts) > 3:
+ start = parse_ass_time(parts[1])
+ end = parse_ass_time(parts[2])
+ overlap = False
+ for rng in parsed_ranges:
+ if start < rng['end'] and end > rng['start']:
+ overlap = True
+ break
+ if overlap:
+ continue
+ filtered_lines.append(line)
+ return "\n".join(filtered_lines)
+ elif subtitle_type == 'srt':
+ subtitles = list(srt.parse(sub_content))
+ filtered = []
+ for sub in subtitles:
+ start = sub.start.total_seconds()
+ end = sub.end.total_seconds()
+ overlap = False
+ for rng in parsed_ranges:
+ if start < rng['end'] and end > rng['start']:
+ overlap = True
+ break
+ if not overlap:
+ filtered.append(sub)
+ return srt.compose(filtered)
+ else:
+ return sub_content
+
+def normalize_exclude_time_ranges(exclude_time_ranges):
+ norm = []
+ for rng in exclude_time_ranges:
+ start = rng.get("start")
+ end = rng.get("end")
+ if not isinstance(start, str) or not isinstance(end, str):
+ raise ValueError("exclude_time_ranges start/end must be strings in hh:mm:ss.ms format.")
+ start_sec = parse_time_string(start)
+ end_sec = parse_time_string(end)
+ if start_sec < 0 or end_sec < 0:
+ raise ValueError("exclude_time_ranges start/end must be non-negative.")
+ if end_sec <= start_sec:
+ raise ValueError("exclude_time_ranges end must be strictly greater than start.")
+ norm.append({"start": start, "end": end})
+ return norm
+
+def generate_ass_captions_v1(video_url, captions, settings, replace, exclude_time_ranges, job_id, language='auto', PlayResX=None, PlayResY=None):
+ """
+ Captioning process with transcription fallback and multiple styles.
+ Integrates with the updated logic for positioning and alignment.
+ If PlayResX and PlayResY are provided, use them for ASS generation; otherwise, get from video.
+ """
+ try:
+ # Normalize exclude_time_ranges to ensure start/end are floats
+ if exclude_time_ranges:
+ exclude_time_ranges = normalize_exclude_time_ranges(exclude_time_ranges)
+
+ if not isinstance(settings, dict):
+ logger.error(f"Job {job_id}: 'settings' should be a dictionary.")
+ return {"error": "'settings' should be a dictionary."}
+
+ # Normalize keys by replacing hyphens with underscores
+ style_options = {k.replace('-', '_'): v for k, v in settings.items()}
+
+ if not isinstance(replace, list):
+ logger.error(f"Job {job_id}: 'replace' should be a list of objects with 'find' and 'replace' keys.")
+ return {"error": "'replace' should be a list of objects with 'find' and 'replace' keys."}
+
+ # Convert 'replace' list to dictionary
+ replace_dict = {}
+ for item in replace:
+ if 'find' in item and 'replace' in item:
+ replace_dict[item['find']] = item['replace']
+ else:
+ logger.warning(f"Job {job_id}: Invalid replace item {item}. Skipping.")
+
+ # Handle deprecated 'highlight_color' by merging it into 'word_color'
+ if 'highlight_color' in style_options:
+ logger.warning(f"Job {job_id}: 'highlight_color' is deprecated; merging into 'word_color'.")
+ style_options['word_color'] = style_options.pop('highlight_color')
+
+ # Check font availability
+ font_family = style_options.get('font_family', 'Arial')
+ available_fonts = get_available_fonts()
+ if font_family not in available_fonts:
+ logger.warning(f"Job {job_id}: Font '{font_family}' not found.")
+ # Return font error with available_fonts
+ return {"error": f"Font '{font_family}' not available.", "available_fonts": available_fonts}
+
+ logger.info(f"Job {job_id}: Font '{font_family}' is available.")
+
+ # Determine if captions is a URL or raw content
+ if captions and is_url(captions):
+ logger.info(f"Job {job_id}: Captions provided as URL. Downloading captions.")
+ try:
+ captions_content = download_captions(captions)
+ except Exception as e:
+ logger.error(f"Job {job_id}: Failed to download captions: {str(e)}")
+ return {"error": f"Failed to download captions: {str(e)}"}
+ elif captions:
+ logger.info(f"Job {job_id}: Captions provided as raw content.")
+ captions_content = captions
+ else:
+ captions_content = None
+
+ # Download the video
+ try:
+ video_path = download_file(video_url, LOCAL_STORAGE_PATH)
+ logger.info(f"Job {job_id}: Video downloaded to {video_path}")
+ except Exception as e:
+ logger.error(f"Job {job_id}: Video download error: {str(e)}")
+ # For non-font errors, do NOT include available_fonts
+ return {"error": str(e)}
+
+ # Get video resolution, unless provided
+ if PlayResX is not None and PlayResY is not None:
+ video_resolution = (PlayResX, PlayResY)
+ logger.info(f"Job {job_id}: Using provided PlayResX/PlayResY = {PlayResX}x{PlayResY}")
+ else:
+ video_resolution = get_video_resolution(video_path)
+ logger.info(f"Job {job_id}: Video resolution detected = {video_resolution[0]}x{video_resolution[1]}")
+
+ # Determine style type
+ style_type = style_options.get('style', 'classic').lower()
+ logger.info(f"Job {job_id}: Using style '{style_type}' for captioning.")
+
+ # Determine subtitle content
+ if captions_content:
+ # Check if it's ASS by looking for '[Script Info]'
+ if '[Script Info]' in captions_content:
+ # It's ASS directly
+ subtitle_content = captions_content
+ subtitle_type = 'ass'
+ logger.info(f"Job {job_id}: Detected ASS formatted captions.")
+ else:
+ # Treat as SRT
+ logger.info(f"Job {job_id}: Detected SRT formatted captions.")
+ # Validate style for SRT
+ if style_type != 'classic':
+ error_message = "Only 'classic' style is supported for SRT captions."
+ logger.error(f"Job {job_id}: {error_message}")
+ return {"error": error_message}
+ transcription_result = srt_to_transcription_result(captions_content)
+ # Generate ASS based on chosen style
+ subtitle_content = process_subtitle_events(transcription_result, style_type, style_options, replace_dict, video_resolution)
+ subtitle_type = 'ass'
+ else:
+ # No captions provided, generate transcription
+ logger.info(f"Job {job_id}: No captions provided, generating transcription.")
+ transcription_result = generate_transcription(video_path, language=language)
+ # Generate ASS based on chosen style
+ subtitle_content = process_subtitle_events(transcription_result, style_type, style_options, replace_dict, video_resolution)
+ subtitle_type = 'ass'
+
+ # Check for subtitle processing errors
+ if isinstance(subtitle_content, dict) and 'error' in subtitle_content:
+ logger.error(f"Job {job_id}: {subtitle_content['error']}")
+ # Only include 'available_fonts' if it's a font-related error
+ if 'available_fonts' in subtitle_content:
+ return {"error": subtitle_content['error'], "available_fonts": subtitle_content.get('available_fonts', [])}
+ else:
+ return {"error": subtitle_content['error']}
+
+ # After subtitle_content is generated and before saving to file:
+ if exclude_time_ranges:
+ subtitle_content = filter_subtitle_lines(subtitle_content, exclude_time_ranges, subtitle_type)
+ if subtitle_type == 'ass':
+ logger.info(f"Job {job_id}: Filtered ASS Dialogue lines due to exclude_time_ranges.")
+ elif subtitle_type == 'srt':
+ logger.info(f"Job {job_id}: Filtered SRT subtitle blocks due to exclude_time_ranges.")
+
+ # Save the subtitle content
+ subtitle_filename = f"{job_id}.{subtitle_type}"
+ subtitle_path = os.path.join(LOCAL_STORAGE_PATH, subtitle_filename)
+ try:
+ with open(subtitle_path, 'w', encoding='utf-8') as f:
+ f.write(subtitle_content)
+ logger.info(f"Job {job_id}: Subtitle file saved to {subtitle_path}")
+ except Exception as e:
+ logger.error(f"Job {job_id}: Failed to save subtitle file: {str(e)}")
+ return {"error": f"Failed to save subtitle file: {str(e)}"}
+
+ return subtitle_path
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error in generate_ass_captions_v1: {str(e)}", exc_info=True)
+ return {"error": str(e)}
diff --git a/services/audio_mixing.py b/services/audio_mixing.py
new file mode 100644
index 0000000000000000000000000000000000000000..f8553d61a3c539d966cddfed0b6a62a33ff48558
--- /dev/null
+++ b/services/audio_mixing.py
@@ -0,0 +1,84 @@
+# 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 subprocess
+from services.file_management import download_file
+
+STORAGE_PATH = "/tmp/"
+
+def get_duration(file_path):
+ cmd = ['ffprobe', '-v', 'error', '-show_entries', 'format=duration', '-of', 'default=noprint_wrappers=1:nokey=1', file_path]
+ result = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ return float(result.stdout)
+
+def process_audio_mixing(video_url, audio_url, video_vol, audio_vol, output_length, job_id, webhook_url=None):
+ video_path = download_file(video_url, STORAGE_PATH)
+ audio_path = download_file(audio_url, STORAGE_PATH)
+ output_path = os.path.join(STORAGE_PATH, f"{job_id}.mp4")
+
+ video_duration = get_duration(video_path)
+ audio_duration = get_duration(audio_path)
+
+ # Explicitly set output duration based on output_length
+ output_duration = video_duration if output_length == 'video' else audio_duration
+
+ # Prepare FFmpeg command
+ cmd = ['ffmpeg', '-y']
+
+ # Input video
+ cmd.extend(['-i', video_path])
+
+ # Input audio
+ cmd.extend(['-i', audio_path])
+
+ # Video settings
+ if output_length == 'audio' and audio_duration > video_duration:
+ cmd.extend(['-stream_loop', '-1']) # Loop video only if output_length is 'audio' and audio is longer
+
+ # Audio settings
+ audio_filter = f'[1:a]volume={audio_vol/100}'
+ if output_length == 'video':
+ audio_filter += f',atrim=duration={video_duration}'
+ audio_filter += '[a]'
+ cmd.extend(['-filter_complex', audio_filter])
+
+ # Output settings
+ cmd.extend(['-map', '0:v']) # Map video from first input
+ cmd.extend(['-map', '[a]']) # Map processed audio
+
+ if output_length == 'audio' and audio_duration > video_duration:
+ cmd.extend(['-c:v', 'libx264']) # Re-encode video if looping
+ else:
+ cmd.extend(['-c:v', 'copy']) # Copy video codec otherwise
+
+ cmd.extend(['-c:a', 'aac']) # Always encode audio to AAC
+
+ # Explicitly set output duration
+ cmd.extend(['-t', str(output_duration)])
+
+ cmd.append(output_path)
+
+ # Run FFmpeg command
+ subprocess.run(cmd, check=True)
+
+ # Clean up input files
+ os.remove(video_path)
+ os.remove(audio_path)
+
+ return output_path
\ No newline at end of file
diff --git a/services/authentication.py b/services/authentication.py
new file mode 100644
index 0000000000000000000000000000000000000000..2b546dc0f4723915752309d791850697ef04bb12
--- /dev/null
+++ b/services/authentication.py
@@ -0,0 +1,31 @@
+# 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 functools import wraps
+from flask import request, jsonify
+from config import API_KEY
+
+def authenticate(func):
+ @wraps(func)
+ def wrapper(*args, **kwargs):
+ api_key = request.headers.get('X-API-Key')
+
+ if api_key != API_KEY:
+ return jsonify({"message": "Unauthorized"}), 401
+ return func(*args, **kwargs)
+ return wrapper
diff --git a/services/caption_video.py b/services/caption_video.py
new file mode 100644
index 0000000000000000000000000000000000000000..8a93cb07d42f5ba5bf73ee0e65689f9c00b5168d
--- /dev/null
+++ b/services/caption_video.py
@@ -0,0 +1,237 @@
+# 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 ffmpeg
+import logging
+import requests
+import subprocess
+from services.file_management import download_file
+
+# Set the default local storage directory
+STORAGE_PATH = "/tmp/"
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Define the path to the fonts directory
+FONTS_DIR = '/usr/share/fonts/custom'
+
+# Create the FONT_PATHS dictionary by reading the fonts directory
+FONT_PATHS = {}
+for font_file in os.listdir(FONTS_DIR):
+ if font_file.endswith('.ttf') or font_file.endswith('.TTF'):
+ font_name = os.path.splitext(font_file)[0]
+ FONT_PATHS[font_name] = os.path.join(FONTS_DIR, font_file)
+# logger.info(f"Available fonts: {FONT_PATHS}")
+
+# Create a list of acceptable font names
+ACCEPTABLE_FONTS = list(FONT_PATHS.keys())
+#logger.info(f"Acceptable font names: {ACCEPTABLE_FONTS}")
+
+# Match font files with fontconfig names
+def match_fonts():
+ try:
+ result = subprocess.run(['fc-list', ':family'], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ if result.returncode == 0:
+ fontconfig_fonts = result.stdout.split('\n')
+ fontconfig_fonts = list(set(fontconfig_fonts)) # Remove duplicates
+ matched_fonts = {}
+ for font_file in FONT_PATHS.keys():
+ for fontconfig_font in fontconfig_fonts:
+ if font_file.lower() in fontconfig_font.lower():
+ matched_fonts[font_file] = fontconfig_font.strip()
+
+ # Parse and output the matched font names
+ unique_font_names = set()
+ for font in matched_fonts.values():
+ font_name = font.split(':')[1].strip()
+ unique_font_names.add(font_name)
+
+ # Remove duplicates from font_name and sort them alphabetically
+ unique_font_names = sorted(list(set(unique_font_names)))
+
+ # for font_name in unique_font_names:
+ # print(font_name)
+ else:
+ logger.error(f"Error matching fonts: {result.stderr}")
+ except Exception as e:
+ logger.error(f"Exception while matching fonts: {str(e)}")
+
+match_fonts()
+
+def generate_style_line(options):
+ """Generate ASS style line from options."""
+ style_options = {
+ 'Name': 'Default',
+ 'Fontname': options.get('font_name', 'Arial'),
+ 'Fontsize': options.get('font_size', 12),
+ 'PrimaryColour': options.get('primary_color', '&H00FFFFFF'),
+ 'OutlineColour': options.get('outline_color', '&H00000000'),
+ 'BackColour': options.get('back_color', '&H00000000'),
+ 'Bold': options.get('bold', 0),
+ 'Italic': options.get('italic', 0),
+ 'Underline': options.get('underline', 0),
+ 'StrikeOut': options.get('strikeout', 0),
+ 'ScaleX': 100,
+ 'ScaleY': 100,
+ 'Spacing': 0,
+ 'Angle': 0,
+ 'BorderStyle': 1,
+ 'Outline': options.get('outline', 1),
+ 'Shadow': options.get('shadow', 0),
+ 'Alignment': options.get('alignment', 2),
+ 'MarginL': options.get('margin_l', 10),
+ 'MarginR': options.get('margin_r', 10),
+ 'MarginV': options.get('margin_v', 10),
+ 'Encoding': options.get('encoding', 1)
+ }
+ return f"Style: {','.join(str(v) for v in style_options.values())}"
+
+def process_captioning(file_url, caption_srt, caption_type, options, job_id):
+ """Process video captioning using FFmpeg."""
+ try:
+ logger.info(f"Job {job_id}: Starting download of file from {file_url}")
+ video_path = download_file(file_url, STORAGE_PATH)
+ logger.info(f"Job {job_id}: File downloaded to {video_path}")
+
+ subtitle_extension = '.' + caption_type
+ srt_path = os.path.join(STORAGE_PATH, f"{job_id}{subtitle_extension}")
+ options = convert_array_to_collection(options)
+ caption_style = ""
+
+ if caption_type == 'ass':
+ style_string = generate_style_line(options)
+ caption_style = f"""
+[Script Info]
+Title: Highlight Current Word
+ScriptType: v4.00+
+[V4+ Styles]
+Format: Name, Fontname, Fontsize, PrimaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
+{style_string}
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+"""
+ logger.info(f"Job {job_id}: Generated ASS style string: {style_string}")
+
+ if caption_srt.startswith("https"):
+ # Download the file if caption_srt is a URL
+ logger.info(f"Job {job_id}: Downloading caption file from {caption_srt}")
+ response = requests.get(caption_srt)
+ response.raise_for_status() # Raise an exception for bad status codes
+ if caption_type in ['srt','vtt']:
+ with open(srt_path, 'wb') as srt_file:
+ srt_file.write(response.content)
+ else:
+ subtitle_content = caption_style + response.text
+ with open(srt_path, 'w') as srt_file:
+ srt_file.write(subtitle_content)
+ logger.info(f"Job {job_id}: Caption file downloaded to {srt_path}")
+ else:
+ # Write caption_srt content directly to file
+ subtitle_content = caption_style + caption_srt
+ with open(srt_path, 'w') as srt_file:
+ srt_file.write(subtitle_content)
+ logger.info(f"Job {job_id}: SRT file created at {srt_path}")
+
+ output_path = os.path.join(STORAGE_PATH, f"{job_id}_captioned.mp4")
+ logger.info(f"Job {job_id}: Output path set to {output_path}")
+
+ # Ensure font_name is converted to the full font path
+ font_name = options.get('font_name', 'Arial')
+ if font_name in FONT_PATHS:
+ selected_font = FONT_PATHS[font_name]
+ logger.info(f"Job {job_id}: Font path set to {selected_font}")
+ else:
+ selected_font = FONT_PATHS.get('Arial')
+ logger.warning(f"Job {job_id}: Font {font_name} not found. Using default font Arial.")
+
+ # For ASS subtitles, we should avoid overriding styles
+ if subtitle_extension == '.ass':
+ # Use the subtitles filter without force_style
+ subtitle_filter = f"subtitles='{srt_path}'"
+ logger.info(f"Job {job_id}: Using ASS subtitle filter: {subtitle_filter}")
+ else:
+ # Construct FFmpeg filter options for subtitles with detailed styling
+ subtitle_filter = f"subtitles={srt_path}:force_style='"
+ style_options = {
+ 'FontName': font_name, # Use the font name instead of the font file path
+ 'FontSize': options.get('font_size', 24),
+ 'PrimaryColour': options.get('primary_color', '&H00FFFFFF'),
+ 'SecondaryColour': options.get('secondary_color', '&H00000000'),
+ 'OutlineColour': options.get('outline_color', '&H00000000'),
+ 'BackColour': options.get('back_color', '&H00000000'),
+ 'Bold': options.get('bold', 0),
+ 'Italic': options.get('italic', 0),
+ 'Underline': options.get('underline', 0),
+ 'StrikeOut': options.get('strikeout', 0),
+ 'Alignment': options.get('alignment', 2),
+ 'MarginV': options.get('margin_v', 10),
+ 'MarginL': options.get('margin_l', 10),
+ 'MarginR': options.get('margin_r', 10),
+ 'Outline': options.get('outline', 1),
+ 'Shadow': options.get('shadow', 0),
+ 'Blur': options.get('blur', 0),
+ 'BorderStyle': options.get('border_style', 1),
+ 'Encoding': options.get('encoding', 1),
+ 'Spacing': options.get('spacing', 0),
+ 'Angle': options.get('angle', 0),
+ 'UpperCase': options.get('uppercase', 0)
+ }
+
+ # Add only populated options to the subtitle filter
+ subtitle_filter += ','.join(f"{k}={v}" for k, v in style_options.items() if v is not None)
+ subtitle_filter += "'"
+ logger.info(f"Job {job_id}: Using subtitle filter: {subtitle_filter}")
+
+ try:
+ # Log the FFmpeg command for debugging
+ logger.info(f"Job {job_id}: Running FFmpeg with filter: {subtitle_filter}")
+
+ # Run FFmpeg to add subtitles to the video
+ ffmpeg.input(video_path).output(
+ output_path,
+ vf=subtitle_filter,
+ acodec='copy'
+ ).run()
+ logger.info(f"Job {job_id}: FFmpeg processing completed, output file at {output_path}")
+ except ffmpeg.Error as e:
+ # Log the FFmpeg stderr output
+ if e.stderr:
+ error_message = e.stderr.decode('utf8')
+ else:
+ error_message = 'Unknown FFmpeg error'
+ logger.error(f"Job {job_id}: FFmpeg error: {error_message}")
+ raise
+
+ # The upload process will be handled by the calling function
+ return output_path
+
+ # Clean up local files
+ os.remove(video_path)
+ os.remove(srt_path)
+ os.remove(output_path)
+ logger.info(f"Job {job_id}: Local files cleaned up")
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error in process_captioning: {str(e)}")
+ raise
+
+def convert_array_to_collection(options):
+ logger.info(f"Converting options array to dictionary: {options}")
+ return {item["option"]: item["value"] for item in options}
diff --git a/services/cloud_storage.py b/services/cloud_storage.py
new file mode 100644
index 0000000000000000000000000000000000000000..936572d2555cfbd6f3cceff3199f2edec796e466
--- /dev/null
+++ b/services/cloud_storage.py
@@ -0,0 +1,118 @@
+# 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 abc import ABC, abstractmethod
+from services.gcp_toolkit import upload_to_gcs
+from services.s3_toolkit import upload_to_s3
+from config import validate_env_vars
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+def parse_s3_url(s3_url):
+ """Parse S3 URL to extract bucket name, region, and endpoint URL."""
+ parsed_url = urlparse(s3_url)
+
+ # Extract bucket name from the host
+ bucket_name = parsed_url.hostname.split('.')[0]
+
+ # Extract region from the host
+ region = parsed_url.hostname.split('.')[1]
+
+ return bucket_name, region
+
+class CloudStorageProvider(ABC):
+ @abstractmethod
+ def upload_file(self, file_path: str) -> str:
+ pass
+
+class GCPStorageProvider(CloudStorageProvider):
+ def __init__(self):
+ self.bucket_name = os.getenv('GCP_BUCKET_NAME')
+
+ def upload_file(self, file_path: str) -> str:
+ return upload_to_gcs(file_path, self.bucket_name)
+
+class S3CompatibleProvider(CloudStorageProvider):
+ def __init__(self):
+
+ self.endpoint_url = os.getenv('S3_ENDPOINT_URL')
+ self.access_key = os.getenv('S3_ACCESS_KEY')
+ self.secret_key = os.getenv('S3_SECRET_KEY')
+ self.bucket_name = os.environ.get('S3_BUCKET_NAME', '')
+ self.region = os.environ.get('S3_REGION', '')
+
+ # Check if endpoint is Digital Ocean and bucket name or region is missing
+ if (self.endpoint_url and
+ 'digitalocean' in self.endpoint_url.lower() and
+ (not self.bucket_name or not self.region)):
+
+ logger.info("Digital Ocean endpoint detected with missing bucket or region. Extracting from URL.")
+ try:
+ # Extract bucket name and region from URL like https://sgp-labs.nyc3.digitaloceanspaces.com
+ parsed_url = urlparse(self.endpoint_url)
+ hostname_parts = parsed_url.hostname.split('.')
+
+ # The first part is the bucket name (sgp-labs)
+ if not self.bucket_name:
+ self.bucket_name = hostname_parts[0]
+ logger.info(f"Extracted bucket name from URL: {self.bucket_name}")
+
+ # The second part is the region (nyc3)
+ if not self.region:
+ self.region = hostname_parts[1]
+ logger.info(f"Extracted region from URL: {self.region}")
+
+ except Exception as e:
+ logger.warning(f"Failed to parse Digital Ocean URL: {e}. Using provided values.")
+
+ def upload_file(self, file_path: str) -> str:
+ return upload_to_s3(file_path, self.endpoint_url, self.access_key, self.secret_key, self.bucket_name, self.region)
+
+def get_storage_provider() -> CloudStorageProvider:
+
+ if os.getenv('S3_ENDPOINT_URL'):
+
+ if ('digitalocean' in os.getenv('S3_ENDPOINT_URL').lower()):
+
+ validate_env_vars('S3_DO')
+ else:
+ validate_env_vars('S3')
+
+ return S3CompatibleProvider()
+
+ if os.getenv('GCP_BUCKET_NAME'):
+
+ validate_env_vars('GCP')
+ return GCPStorageProvider()
+
+ raise ValueError(f"No cloud storage settings provided.")
+
+def upload_file(file_path: str) -> str:
+ provider = get_storage_provider()
+ try:
+ logger.info(f"Uploading file to cloud storage: {file_path}")
+ url = provider.upload_file(file_path)
+ logger.info(f"File uploaded successfully: {url}")
+ return url
+ except Exception as e:
+ logger.error(f"Error uploading file to cloud storage: {e}")
+ raise
+
\ No newline at end of file
diff --git a/services/extract_keyframes.py b/services/extract_keyframes.py
new file mode 100644
index 0000000000000000000000000000000000000000..d1e32492a5459c33c90f3a1c42b1b1ad34aedcba
--- /dev/null
+++ b/services/extract_keyframes.py
@@ -0,0 +1,53 @@
+# 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 subprocess
+import json
+from services.file_management import download_file
+
+STORAGE_PATH = "/tmp/"
+
+def process_keyframe_extraction(video_url, job_id):
+ video_path = download_file(video_url, STORAGE_PATH)
+
+ # Extract keyframes
+ output_pattern = os.path.join(STORAGE_PATH, f"{job_id}_%03d.jpg")
+ cmd = [
+ 'ffmpeg',
+ '-i', video_path,
+ '-vf', f"select='eq(pict_type,I)',scale=iw*sar:ih,setsar=1",
+ '-vsync', 'vfr',
+ output_pattern
+ ]
+
+ print(f"Images: {cmd}")
+
+ subprocess.run(cmd, check=True)
+
+ # Upload keyframes to GCS and get URLs
+ output_filenames = []
+ for filename in sorted(os.listdir(STORAGE_PATH)):
+ if filename.startswith(f"{job_id}_") and filename.endswith(".jpg"):
+ file_path = os.path.join(STORAGE_PATH, filename)
+ output_filenames.append(file_path)
+
+ # Clean up input file
+ os.remove(video_path)
+
+ return output_filenames
\ No newline at end of file
diff --git a/services/ffmpeg_toolkit.py b/services/ffmpeg_toolkit.py
new file mode 100644
index 0000000000000000000000000000000000000000..3b4564315c7c9fb4bb714dfe20d8f42546738d9b
--- /dev/null
+++ b/services/ffmpeg_toolkit.py
@@ -0,0 +1,97 @@
+# 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 ffmpeg
+import requests
+from services.file_management import download_file
+
+# Set the default local storage directory
+STORAGE_PATH = "/tmp/"
+
+def process_conversion(media_url, job_id, bitrate='128k', webhook_url=None):
+ """Convert media to MP3 format with specified bitrate."""
+ input_filename = download_file(media_url, os.path.join(STORAGE_PATH, f"{job_id}_input"))
+ output_filename = f"{job_id}.mp3"
+ output_path = os.path.join(STORAGE_PATH, output_filename)
+
+ try:
+ # Convert media file to MP3 with specified bitrate
+ (
+ ffmpeg
+ .input(input_filename)
+ .output(output_path, acodec='libmp3lame', audio_bitrate=bitrate)
+ .overwrite_output()
+ .run(capture_stdout=True, capture_stderr=True)
+ )
+ os.remove(input_filename)
+ print(f"Conversion successful: {output_path} with bitrate {bitrate}")
+
+ # Ensure the output file exists locally before attempting upload
+ if not os.path.exists(output_path):
+ raise FileNotFoundError(f"Output file {output_path} does not exist after conversion.")
+
+ return output_path
+
+ except Exception as e:
+ print(f"Conversion failed: {str(e)}")
+ raise
+
+def process_video_combination(media_urls, job_id, webhook_url=None):
+ """Combine multiple videos into one."""
+ input_files = []
+ output_filename = f"{job_id}.mp4"
+ output_path = os.path.join(STORAGE_PATH, output_filename)
+
+ try:
+ # Download all media files
+ for i, media_item in enumerate(media_urls):
+ url = media_item['video_url']
+ input_filename = download_file(url, os.path.join(STORAGE_PATH, f"{job_id}_input_{i}"))
+ input_files.append(input_filename)
+
+ # Generate an absolute path concat list file for FFmpeg
+ concat_file_path = os.path.join(STORAGE_PATH, f"{job_id}_concat_list.txt")
+ with open(concat_file_path, 'w') as concat_file:
+ for input_file in input_files:
+ # Write absolute paths to the concat list
+ concat_file.write(f"file '{os.path.abspath(input_file)}'\n")
+
+ # Use the concat demuxer to concatenate the videos
+ (
+ ffmpeg.input(concat_file_path, format='concat', safe=0).
+ output(output_path, c='copy').
+ run(overwrite_output=True)
+ )
+
+ # Clean up input files
+ for f in input_files:
+ os.remove(f)
+
+ os.remove(concat_file_path) # Remove the concat list file after the operation
+
+ print(f"Video combination successful: {output_path}")
+
+ # Check if the output file exists locally before upload
+ if not os.path.exists(output_path):
+ raise FileNotFoundError(f"Output file {output_path} does not exist after combination.")
+
+ return output_path
+ except Exception as e:
+ print(f"Video combination failed: {str(e)}")
+ raise
diff --git a/services/file_management.py b/services/file_management.py
new file mode 100644
index 0000000000000000000000000000000000000000..256c299edf32235633e4752f92b4b33a68b89237
--- /dev/null
+++ b/services/file_management.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.
+
+
+
+import os
+import uuid
+import requests
+from urllib.parse import urlparse, parse_qs
+import mimetypes
+
+def get_extension_from_url(url):
+ """Extract file extension from URL or content type.
+
+ Args:
+ url (str): The URL to extract the extension from
+
+ Returns:
+ str: The file extension including the dot (e.g., '.jpg')
+
+ Raises:
+ ValueError: If no valid extension can be determined from the URL or content type
+ """
+ # First try to get extension from URL
+ parsed_url = urlparse(url)
+ path = parsed_url.path
+ if path:
+ ext = os.path.splitext(path)[1].lower()
+ if ext:
+ return ext
+
+ # If no extension in URL, try to determine from content type
+ try:
+ response = requests.head(url, allow_redirects=True)
+ content_type = response.headers.get('content-type', '').split(';')[0]
+ ext = mimetypes.guess_extension(content_type)
+ if ext:
+ return ext.lower()
+ except:
+ pass
+
+ # If we can't determine the extension, raise an error
+ raise ValueError(f"Could not determine file extension from URL: {url}")
+
+def download_file(url, storage_path="/tmp/"):
+ """Download a file from URL to local storage."""
+ # Create storage directory if it doesn't exist
+ os.makedirs(storage_path, exist_ok=True)
+
+ file_id = str(uuid.uuid4())
+ extension = get_extension_from_url(url)
+ local_filename = os.path.join(storage_path, f"{file_id}{extension}")
+
+ try:
+ response = requests.get(url, stream=True)
+ response.raise_for_status()
+
+ with open(local_filename, 'wb') as f:
+ for chunk in response.iter_content(chunk_size=8192):
+ if chunk:
+ f.write(chunk)
+
+ return local_filename
+ except Exception as e:
+ if os.path.exists(local_filename):
+ os.remove(local_filename)
+ raise e
+
diff --git a/services/gcp_toolkit.py b/services/gcp_toolkit.py
new file mode 100644
index 0000000000000000000000000000000000000000..30229a7ca8017c1322c46cdad72cd91b3779ef3a
--- /dev/null
+++ b/services/gcp_toolkit.py
@@ -0,0 +1,71 @@
+# 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 json
+import logging
+from google.oauth2 import service_account
+from google.cloud import storage
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# GCS environment variables
+GCP_BUCKET_NAME = os.getenv('GCP_BUCKET_NAME')
+STORAGE_PATH = "/tmp/"
+gcs_client = None
+
+def initialize_gcp_client():
+ GCP_SA_CREDENTIALS = os.getenv('GCP_SA_CREDENTIALS')
+
+ if not GCP_SA_CREDENTIALS:
+ #logger.warning("GCP credentials not found. Skipping GCS client initialization.")
+ return None # Skip client initialization if credentials are missing
+
+ # Define the required scopes for Google Cloud Storage
+ GCS_SCOPES = ['https://www.googleapis.com/auth/devstorage.full_control']
+
+ try:
+ credentials_info = json.loads(GCP_SA_CREDENTIALS)
+ gcs_credentials = service_account.Credentials.from_service_account_info(
+ credentials_info,
+ scopes=GCS_SCOPES
+ )
+ return storage.Client(credentials=gcs_credentials)
+ except Exception as e:
+ logger.error(f"Failed to initialize GCS client: {e}")
+ return None
+
+# Initialize the GCS client
+gcs_client = initialize_gcp_client()
+
+def upload_to_gcs(file_path, bucket_name=GCP_BUCKET_NAME):
+ if not gcs_client:
+ raise ValueError("GCS client is not initialized. Skipping file upload.")
+
+ try:
+ logger.info(f"Uploading file to Google Cloud Storage: {file_path}")
+ bucket = gcs_client.bucket(bucket_name)
+ blob = bucket.blob(os.path.basename(file_path))
+ blob.upload_from_filename(file_path)
+ logger.info(f"File uploaded successfully to GCS: {blob.public_url}")
+ return blob.public_url
+ except Exception as e:
+ logger.error(f"Error uploading file to GCS: {e}")
+ raise
diff --git a/services/image_to_video.py b/services/image_to_video.py
new file mode 100644
index 0000000000000000000000000000000000000000..a8c8c22e6f5fa3a82bacc0abe8a7623127fb6a2d
--- /dev/null
+++ b/services/image_to_video.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.
+
+
+
+import os
+import subprocess
+import logging
+from services.file_management import download_file
+from PIL import Image
+
+STORAGE_PATH = "/tmp/"
+logger = logging.getLogger(__name__)
+
+def process_image_to_video(image_url, length, frame_rate, zoom_speed, job_id, webhook_url=None):
+ try:
+ # Download the image file
+ image_path = download_file(image_url, STORAGE_PATH)
+ logger.info(f"Downloaded image to {image_path}")
+
+ # Get image dimensions using Pillow
+ with Image.open(image_path) as img:
+ width, height = img.size
+ logger.info(f"Original image dimensions: {width}x{height}")
+
+ # Prepare the output path
+ output_path = os.path.join(STORAGE_PATH, f"{job_id}.mp4")
+
+ # Determine orientation and set appropriate dimensions
+ if width > height:
+ scale_dims = "7680:4320"
+ output_dims = "1920x1080"
+ else:
+ scale_dims = "4320:7680"
+ output_dims = "1080x1920"
+
+ # Calculate total frames and zoom factor
+ total_frames = float(length * frame_rate)
+ zoom_factor = 1 + (zoom_speed * length)
+
+ logger.info(f"Using scale dimensions: {scale_dims}, output dimensions: {output_dims}")
+ logger.info(f"Video length: {length}s, Frame rate: {frame_rate}fps, Total frames: {total_frames}")
+ logger.info(f"Zoom speed: {zoom_speed}/s, Final zoom factor: {zoom_factor}")
+
+ # Prepare FFmpeg command
+ cmd = [
+ 'ffmpeg', '-framerate', str(frame_rate), '-loop', '1', '-i', image_path,
+ '-vf', f"scale={scale_dims},zoompan=z='min(1+({zoom_speed}*{length})*on/{total_frames}, {zoom_factor})':d={total_frames}:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':s={output_dims}",
+ '-c:v', 'libx264', '-t', str(length), '-pix_fmt', 'yuv420p', output_path
+ ]
+
+ logger.info(f"Running FFmpeg command: {' '.join(cmd)}")
+
+ # Run FFmpeg command
+ result = subprocess.run(cmd, capture_output=True, text=True)
+ if result.returncode != 0:
+ logger.error(f"FFmpeg command failed. Error: {result.stderr}")
+ raise subprocess.CalledProcessError(result.returncode, cmd, result.stdout, result.stderr)
+
+ logger.info(f"Video created successfully: {output_path}")
+
+ # Clean up input file
+ os.remove(image_path)
+
+ return output_path
+ except Exception as e:
+ logger.error(f"Error in process_image_to_video: {str(e)}", exc_info=True)
+ raise
\ No newline at end of file
diff --git a/services/s3_toolkit.py b/services/s3_toolkit.py
new file mode 100644
index 0000000000000000000000000000000000000000..1b0dc9709730c8d0a127902989a6d3ab56ed59dd
--- /dev/null
+++ b/services/s3_toolkit.py
@@ -0,0 +1,49 @@
+# 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 boto3
+import logging
+from urllib.parse import urlparse, quote
+
+logger = logging.getLogger(__name__)
+
+def upload_to_s3(file_path, s3_url, access_key, secret_key, bucket_name, region):
+ # Parse the S3 URL into bucket, region, and endpoint
+ #bucket_name, region, endpoint_url = parse_s3_url(s3_url)
+
+ session = boto3.Session(
+ aws_access_key_id=access_key,
+ aws_secret_access_key=secret_key,
+ region_name=region
+ )
+
+ client = session.client('s3', endpoint_url=s3_url)
+
+ try:
+ # Upload the file to the specified S3 bucket
+ with open(file_path, 'rb') as data:
+ client.upload_fileobj(data, bucket_name, os.path.basename(file_path), ExtraArgs={'ACL': 'public-read'})
+
+ # URL encode the filename for the URL
+ encoded_filename = quote(os.path.basename(file_path))
+ file_url = f"{s3_url}/{bucket_name}/{encoded_filename}"
+ return file_url
+ except Exception as e:
+ logger.error(f"Error uploading file to S3: {e}")
+ raise
diff --git a/services/transcription.py b/services/transcription.py
new file mode 100644
index 0000000000000000000000000000000000000000..0691be0d3795c570569d7dfdb966685e62babfd2
--- /dev/null
+++ b/services/transcription.py
@@ -0,0 +1,177 @@
+# 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 whisper
+import srt
+from datetime import timedelta
+from whisper.utils import WriteSRT, WriteVTT
+from services.file_management import download_file
+import logging
+import uuid
+
+# Set up logging
+logger = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO)
+
+# Set the default local storage directory
+STORAGE_PATH = "/tmp/"
+
+def process_transcription(media_url, output_type, max_chars=56, language=None,):
+ """Transcribe media and return the transcript, SRT or ASS file path."""
+ logger.info(f"Starting transcription for media URL: {media_url} with output type: {output_type}")
+ input_filename = download_file(media_url, os.path.join(STORAGE_PATH, 'input_media'))
+ logger.info(f"Downloaded media to local file: {input_filename}")
+
+ try:
+ model = whisper.load_model("base")
+ logger.info("Loaded Whisper model")
+
+ # result = model.transcribe(input_filename)
+ # logger.info("Transcription completed")
+
+ if output_type == 'transcript':
+ result = model.transcribe(input_filename, language=language)
+ output = result['text']
+ logger.info("Generated transcript output")
+ elif output_type in ['srt', 'vtt']:
+
+ result = model.transcribe(input_filename)
+ srt_subtitles = []
+ for i, segment in enumerate(result['segments'], start=1):
+ start = timedelta(seconds=segment['start'])
+ end = timedelta(seconds=segment['end'])
+ text = segment['text'].strip()
+ srt_subtitles.append(srt.Subtitle(i, start, end, text))
+
+ output_content = srt.compose(srt_subtitles)
+
+ # Write the output to a file
+ output_filename = os.path.join(STORAGE_PATH, f"{uuid.uuid4()}.{output_type}")
+ with open(output_filename, 'w') as f:
+ f.write(output_content)
+
+ output = output_filename
+ logger.info(f"Generated {output_type.upper()} output: {output}")
+
+ elif output_type == 'ass':
+ result = model.transcribe(
+ input_filename,
+ word_timestamps=True,
+ task='transcribe',
+ verbose=False
+ )
+ logger.info("Transcription completed with word-level timestamps")
+ # Generate ASS subtitle content
+ ass_content = generate_ass_subtitle(result, max_chars)
+ logger.info("Generated ASS subtitle content")
+
+ output_content = ass_content
+
+ # Write the ASS content to a file
+ output_filename = os.path.join(STORAGE_PATH, f"{uuid.uuid4()}.{output_type}")
+ with open(output_filename, 'w') as f:
+ f.write(output_content)
+ output = output_filename
+ logger.info(f"Generated {output_type.upper()} output: {output}")
+ else:
+ raise ValueError("Invalid output type. Must be 'transcript', 'srt', or 'vtt'.")
+
+ os.remove(input_filename)
+ logger.info(f"Removed local file: {input_filename}")
+ logger.info(f"Transcription successful, output type: {output_type}")
+ return output
+ except Exception as e:
+ logger.error(f"Transcription failed: {str(e)}")
+ raise
+
+
+def generate_ass_subtitle(result, max_chars):
+ """Generate ASS subtitle content with highlighted current words, showing one line at a time."""
+ logger.info("Generate ASS subtitle content with highlighted current words")
+ # ASS file header
+ ass_content = ""
+
+ # Helper function to format time
+ def format_time(t):
+ hours = int(t // 3600)
+ minutes = int((t % 3600) // 60)
+ seconds = int(t % 60)
+ centiseconds = int(round((t - int(t)) * 100))
+ return f"{hours}:{minutes:02d}:{seconds:02d}.{centiseconds:02d}"
+
+ max_chars_per_line = max_chars # Maximum characters per line
+
+ # Process each segment
+ for segment in result['segments']:
+ words = segment.get('words', [])
+ if not words:
+ continue # Skip if no word-level timestamps
+
+ # Group words into lines
+ lines = []
+ current_line = []
+ current_line_length = 0
+ for word_info in words:
+ word_length = len(word_info['word']) + 1 # +1 for space
+ if current_line_length + word_length > max_chars_per_line:
+ lines.append(current_line)
+ current_line = [word_info]
+ current_line_length = word_length
+ else:
+ current_line.append(word_info)
+ current_line_length += word_length
+ if current_line:
+ lines.append(current_line)
+
+ # Generate events for each line
+ for line in lines:
+ line_start_time = line[0]['start']
+ line_end_time = line[-1]['end']
+
+ # Generate events for highlighting each word
+ for i, word_info in enumerate(line):
+ start_time = word_info['start']
+ end_time = word_info['end']
+ current_word = word_info['word']
+
+ # Build the line text with highlighted current word
+ caption_parts = []
+ for w in line:
+ word_text = w['word']
+ if w == word_info:
+ # Highlight current word
+ caption_parts.append(r'{\c&H00FFFF&}' + word_text)
+ else:
+ # Default color
+ caption_parts.append(r'{\c&HFFFFFF&}' + word_text)
+ caption_with_highlight = ' '.join(caption_parts)
+
+ # Format times
+ start = format_time(start_time)
+ # End the dialogue event when the next word starts or at the end of the line
+ if i + 1 < len(line):
+ end_time = line[i + 1]['start']
+ else:
+ end_time = line_end_time
+ end = format_time(end_time)
+
+ # Add the dialogue line
+ ass_content += f"Dialogue: 0,{start},{end},Default,,0,0,0,,{caption_with_highlight}\n"
+
+ return ass_content
\ No newline at end of file
diff --git a/services/v1/audio/concatenate.py b/services/v1/audio/concatenate.py
new file mode 100644
index 0000000000000000000000000000000000000000..1670eed05b367dc8d6c6a57ab812ef980bbe7853
--- /dev/null
+++ b/services/v1/audio/concatenate.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.
+
+
+
+import os
+import ffmpeg
+from services.file_management import download_file
+from config import LOCAL_STORAGE_PATH
+
+def process_audio_concatenate(media_urls, job_id, webhook_url=None):
+ """Combine multiple audio files into one."""
+ input_files = []
+ output_filename = f"{job_id}.mp3"
+ output_path = os.path.join(LOCAL_STORAGE_PATH, output_filename)
+
+ try:
+ # Download all media files
+ for i, media_item in enumerate(media_urls):
+ url = media_item['audio_url']
+ input_filename = download_file(url, os.path.join(LOCAL_STORAGE_PATH, f"{job_id}_input_{i}"))
+ input_files.append(input_filename)
+
+ # Generate an absolute path concat list file for FFmpeg
+ concat_file_path = os.path.join(LOCAL_STORAGE_PATH, f"{job_id}_concat_list.txt")
+ with open(concat_file_path, 'w') as concat_file:
+ for input_file in input_files:
+ # Write absolute paths to the concat list
+ concat_file.write(f"file '{os.path.abspath(input_file)}'\n")
+
+ # Use the concat demuxer to concatenate the audio files without re-encoding
+ (
+ ffmpeg.input(concat_file_path, format='concat', safe=0).
+ output(output_path, c='copy').
+ run(overwrite_output=True)
+ )
+
+ # Clean up input files
+ for f in input_files:
+ os.remove(f)
+
+ os.remove(concat_file_path) # Remove the concat list file after the operation
+
+ print(f"Audio combination successful: {output_path}")
+
+ # Check if the output file exists locally before upload
+ if not os.path.exists(output_path):
+ raise FileNotFoundError(f"Output file {output_path} does not exist after combination.")
+
+ return output_path
+ except Exception as e:
+ print(f"Audio combination failed: {str(e)}")
+ raise
\ No newline at end of file
diff --git a/services/v1/ffmpeg/ffmpeg_compose.py b/services/v1/ffmpeg/ffmpeg_compose.py
new file mode 100644
index 0000000000000000000000000000000000000000..5a6713a2aa685c39b65d1251cbeb5aba53bc6950
--- /dev/null
+++ b/services/v1/ffmpeg/ffmpeg_compose.py
@@ -0,0 +1,177 @@
+# 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 subprocess
+import json
+import re
+from services.file_management import download_file
+from config import LOCAL_STORAGE_PATH
+
+def get_extension_from_format(format_name):
+ # Mapping of common format names to file extensions
+ format_to_extension = {
+ 'mp4': 'mp4',
+ 'mov': 'mov',
+ 'avi': 'avi',
+ 'mkv': 'mkv',
+ 'webm': 'webm',
+ 'gif': 'gif',
+ 'apng': 'apng',
+ 'jpg': 'jpg',
+ 'jpeg': 'jpg',
+ 'png': 'png',
+ 'image2': 'png', # Assume png for image2 format
+ 'rawvideo': 'raw',
+ 'mp3': 'mp3',
+ 'wav': 'wav',
+ 'aac': 'aac',
+ 'flac': 'flac',
+ 'ogg': 'ogg'
+ }
+ return format_to_extension.get(format_name.lower(), 'mp4') # Default to mp4 if unknown
+
+def get_metadata(filename, metadata_requests, job_id):
+ metadata = {}
+ if metadata_requests.get('thumbnail'):
+ thumbnail_filename = f"{os.path.splitext(filename)[0]}_thumbnail.jpg"
+ thumbnail_command = [
+ 'ffmpeg',
+ '-i', filename,
+ '-vf', 'select=eq(n\,0)',
+ '-vframes', '1',
+ thumbnail_filename
+ ]
+ try:
+ subprocess.run(thumbnail_command, check=True, capture_output=True, text=True)
+ if os.path.exists(thumbnail_filename):
+ metadata['thumbnail'] = thumbnail_filename # Return local path instead of URL
+ except subprocess.CalledProcessError as e:
+ print(f"Thumbnail generation failed: {e.stderr}")
+
+ if metadata_requests.get('filesize'):
+ metadata['filesize'] = os.path.getsize(filename)
+
+ if metadata_requests.get('encoder') or metadata_requests.get('duration') or metadata_requests.get('bitrate'):
+ ffprobe_command = [
+ 'ffprobe',
+ '-v', 'quiet',
+ '-print_format', 'json',
+ '-show_format',
+ '-show_streams',
+ filename
+ ]
+ result = subprocess.run(ffprobe_command, capture_output=True, text=True)
+ probe_data = json.loads(result.stdout)
+
+ if metadata_requests.get('duration'):
+ metadata['duration'] = float(probe_data['format']['duration'])
+ if metadata_requests.get('bitrate'):
+ metadata['bitrate'] = int(probe_data['format']['bit_rate'])
+
+ if metadata_requests.get('encoder'):
+ metadata['encoder'] = {}
+ for stream in probe_data['streams']:
+ if stream['codec_type'] == 'video':
+ metadata['encoder']['video'] = stream.get('codec_name', 'unknown')
+ elif stream['codec_type'] == 'audio':
+ metadata['encoder']['audio'] = stream.get('codec_name', 'unknown')
+
+ return metadata
+
+def process_ffmpeg_compose(data, job_id):
+ output_filenames = []
+
+ # Build FFmpeg command
+ command = ["ffmpeg"]
+
+ # Add global options
+ for option in data.get("global_options", []):
+ command.append(option["option"])
+ if "argument" in option and option["argument"] is not None:
+ command.append(str(option["argument"]))
+
+ # Add inputs
+ input_paths = []
+ for input_data in data["inputs"]:
+ if "options" in input_data:
+ for option in input_data["options"]:
+ command.append(option["option"])
+ if "argument" in option and option["argument"] is not None:
+ command.append(str(option["argument"]))
+ input_path = download_file(input_data["file_url"], LOCAL_STORAGE_PATH)
+ input_paths.append(input_path)
+ command.extend(["-i", input_path])
+
+ # Add filters
+ subtitles_paths = [] # Track downloaded subtitles/filter files
+ if data.get("filters"):
+ new_filters = []
+ for filter_obj in data["filters"]:
+ filter_str = filter_obj["filter"]
+ def replace_subtitles_url(match):
+ url = match.group(1)
+ local_path = download_file(url, LOCAL_STORAGE_PATH)
+ subtitles_paths.append(local_path)
+ fixed_path = local_path.replace('\\', '/')
+ return f"subtitles='{fixed_path}" # keep the opening quote
+ # Regex: subtitles='' or subtitles=""
+ filter_str = re.sub(r"subtitles=['\"]([^'\"]+)", replace_subtitles_url, filter_str)
+ new_filters.append(filter_str)
+ filter_complex = ";".join(new_filters)
+ command.extend(["-filter_complex", filter_complex])
+
+ # Add outputs
+ for i, output in enumerate(data["outputs"]):
+ format_name = None
+ for option in output["options"]:
+ if option["option"] == "-f":
+ format_name = option.get("argument")
+ break
+
+ extension = get_extension_from_format(format_name) if format_name else 'mp4'
+ output_filename = os.path.join(LOCAL_STORAGE_PATH, f"{job_id}_output_{i}.{extension}")
+ output_filenames.append(output_filename)
+
+ for option in output["options"]:
+ command.append(option["option"])
+ if "argument" in option and option["argument"] is not None:
+ command.append(str(option["argument"]))
+ command.append(output_filename)
+
+ # Execute FFmpeg command
+ try:
+ subprocess.run(command, check=True, capture_output=True, text=True)
+ except subprocess.CalledProcessError as e:
+ raise Exception(f"FFmpeg command failed: {e.stderr}")
+
+ # Clean up input files
+ for input_path in input_paths:
+ if os.path.exists(input_path):
+ os.remove(input_path)
+ # Clean up subtitles/filter files
+ for subtitles_path in subtitles_paths:
+ if os.path.exists(subtitles_path):
+ os.remove(subtitles_path)
+ # Get metadata if requested
+ metadata = []
+ if data.get("metadata"):
+ for output_filename in output_filenames:
+ metadata.append(get_metadata(output_filename, data["metadata"], job_id))
+
+ return output_filenames, metadata
\ No newline at end of file
diff --git a/services/v1/image/convert/image_to_video.py b/services/v1/image/convert/image_to_video.py
new file mode 100644
index 0000000000000000000000000000000000000000..7bce0481b79ad66e68b5a3958b0224d43b7aca20
--- /dev/null
+++ b/services/v1/image/convert/image_to_video.py
@@ -0,0 +1,80 @@
+# 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 subprocess
+import logging
+from services.file_management import download_file
+from PIL import Image
+from config import LOCAL_STORAGE_PATH
+logger = logging.getLogger(__name__)
+
+def process_image_to_video(image_url, length, frame_rate, zoom_speed, job_id, webhook_url=None):
+ try:
+ # Download the image file
+ image_path = download_file(image_url, LOCAL_STORAGE_PATH)
+ logger.info(f"Downloaded image to {image_path}")
+
+ # Get image dimensions using Pillow
+ with Image.open(image_path) as img:
+ width, height = img.size
+ logger.info(f"Original image dimensions: {width}x{height}")
+
+ # Prepare the output path
+ output_path = os.path.join(LOCAL_STORAGE_PATH, f"{job_id}.mp4")
+
+ # Determine orientation and set appropriate dimensions
+ if width > height:
+ scale_dims = "7680:4320"
+ output_dims = "1920x1080"
+ else:
+ scale_dims = "4320:7680"
+ output_dims = "1080x1920"
+
+ # Calculate total frames and zoom factor
+ total_frames = int(length * frame_rate)
+ zoom_factor = 1 + (zoom_speed * length)
+
+ logger.info(f"Using scale dimensions: {scale_dims}, output dimensions: {output_dims}")
+ logger.info(f"Video length: {length}s, Frame rate: {frame_rate}fps, Total frames: {total_frames}")
+ logger.info(f"Zoom speed: {zoom_speed}/s, Final zoom factor: {zoom_factor}")
+
+ # Prepare FFmpeg command with fps filter to ensure correct frame rate
+ cmd = [
+ 'ffmpeg', '-framerate', str(frame_rate), '-loop', '1', '-i', image_path,
+ '-vf', f"scale={scale_dims},zoompan=z='min(1+({zoom_speed}*{length})*on/{total_frames}, {zoom_factor})':d={total_frames}:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':s={output_dims},fps={frame_rate}",
+ '-c:v', 'libx264', '-r', str(frame_rate), '-t', str(length), '-pix_fmt', 'yuv420p', output_path
+ ]
+
+ logger.info(f"Running FFmpeg command: {' '.join(cmd)}")
+
+ # Run FFmpeg command
+ result = subprocess.run(cmd, capture_output=True, text=True)
+ if result.returncode != 0:
+ logger.error(f"FFmpeg command failed. Error: {result.stderr}")
+ raise subprocess.CalledProcessError(result.returncode, cmd, result.stdout, result.stderr)
+
+ logger.info(f"Video created successfully: {output_path}")
+
+ # Clean up input file
+ os.remove(image_path)
+
+ return output_path
+ except Exception as e:
+ logger.error(f"Error in process_image_to_video: {str(e)}", exc_info=True)
+ raise
\ No newline at end of file
diff --git a/services/v1/image/screenshot_webpage.py b/services/v1/image/screenshot_webpage.py
new file mode 100644
index 0000000000000000000000000000000000000000..7b3143be7d6d76a8c324e50953ebcb26dbc7d0af
--- /dev/null
+++ b/services/v1/image/screenshot_webpage.py
@@ -0,0 +1,152 @@
+# 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 service: /v1/playwright/screenshot
+
+import os
+import logging
+from io import BytesIO
+from playwright.sync_api import sync_playwright
+
+# Initialize logger
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+if not logger.hasHandlers():
+ handler = logging.StreamHandler()
+ formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+ handler.setFormatter(formatter)
+ logger.addHandler(handler)
+
+def take_screenshot(data: dict, job_id=None):
+ p = sync_playwright().start()
+ try:
+ browser = p.chromium.launch(headless=True)
+ try:
+ context = browser.new_context(
+ viewport={"width": data.get("viewport_width", 1280), "height": data.get("viewport_height", 720)},
+ device_scale_factor=data.get("device_scale_factor", 1),
+ user_agent=data.get("user_agent")
+ )
+ page = context.new_page()
+
+ # Validate and set headers
+ if data.get("headers"):
+ page.set_extra_http_headers(data["headers"])
+
+ # Validate and set cookies
+ if data.get("cookies"):
+ from urllib.parse import urlparse
+ url_domain = None
+ if data.get("url"):
+ url_domain = urlparse(data["url"]).hostname
+ elif data.get("html"):
+ url_domain = None
+ for cookie in data["cookies"]:
+ cookie.setdefault("path", "/")
+ cookie_domain = cookie["domain"].lstrip(".")
+ if url_domain and not (url_domain == cookie_domain or url_domain.endswith(f".{cookie_domain}")):
+ raise Exception("COOKIE_DOMAIN_MISMATCH")
+ context.add_cookies(data["cookies"])
+
+ # Set page content from html or navigate to url
+ if data.get("html"):
+ page.set_content(data["html"])
+ elif data.get("url"):
+ page.goto(data["url"], timeout=data.get("timeout", 30000), wait_until=data.get("wait_until", "load"))
+ else:
+ raise Exception("MISSING_URL_OR_HTML")
+
+ # Wait for a selector if specified
+ if data.get("wait_for_selector"):
+ try:
+ page.wait_for_selector(data["wait_for_selector"])
+ except Exception as e:
+ raise Exception("WAIT_FOR_SELECTOR_NOT_FOUND")
+
+ # Emulate media features
+ if data.get("emulate"):
+ if "color_scheme" in data["emulate"]:
+ page.emulate_media(color_scheme=data["emulate"]["color_scheme"])
+
+ # Delay if specified
+ if data.get("delay"):
+ page.wait_for_timeout(data["delay"])
+
+ # Inject custom CSS if provided
+ if data.get("css"):
+ page.add_style_tag(content=data["css"])
+ # Inject custom JS if provided
+ if data.get("js"):
+ page.add_script_tag(content=data["js"])
+
+ screenshot_io = BytesIO()
+
+ # Ensure omit_background is only used with PNG
+ if data.get("omit_background", False) and data.get("format", "png") == "jpeg":
+ raise Exception("OMIT_BACKGROUND_JPEG_UNSUPPORTED")
+
+ # and doesn't support quality settings - quality parameter only works with JPEG
+ if data.get("format", "png") == "png" and data.get("quality") is not None:
+ raise Exception("QUALITY_PNG_UNSUPPORTED")
+
+ # Take a screenshot of a specific element or the full page
+ if data.get("selector"):
+ element = page.locator(data["selector"])
+ if element.count() == 0:
+ raise Exception("ELEMENT_NOT_FOUND")
+ screenshot = element.screenshot(
+ type=data.get("format", "png"),
+ quality=data.get("quality"),
+ omit_background=data.get("omit_background")
+ )
+ else:
+ # Validate clip dimensions if provided
+ if data.get("clip"):
+ clip = data["clip"]
+ if clip["x"] < 0 or clip["y"] < 0 or clip["width"] <= 0 or clip["height"] <= 0:
+ raise Exception("INVALID_CLIP_DIMENSIONS")
+ screenshot = page.screenshot(
+ full_page=data.get("full_page", False),
+ type=data.get("format", "png"),
+ quality=data.get("quality"),
+ clip=data.get("clip"),
+ omit_background=data.get("omit_background")
+ )
+
+ screenshot_io.write(screenshot)
+ screenshot_io.seek(0)
+ return screenshot_io
+ finally:
+ browser.close()
+ except Exception as e:
+ logger.error(f"Job {job_id}: Error taking screenshot: {str(e)}", exc_info=True)
+ error_message = str(e)
+ error_map = {
+ "ELEMENT_NOT_FOUND": f"The selector '{data.get('selector')}' was not found on the page. Please check your selector.",
+ "INVALID_CLIP_DIMENSIONS": "Clip dimensions must be positive and non-negative.",
+ "COOKIE_DOMAIN_MISMATCH": "A cookie domain does not match or is not a parent of the URL domain.",
+ "OMIT_BACKGROUND_JPEG_UNSUPPORTED": "'omit_background' is only supported for PNG format.",
+ "MISSING_URL_OR_HTML": "You must provide either a 'url' or 'html' field.",
+ "WAIT_FOR_SELECTOR_NOT_FOUND": "The selector specified in 'wait_for_selector' was not found on the page.",
+ "QUALITY_PNG_UNSUPPORTED": "'quality' is not supported for PNG (default format). Use JPEG format instead.",
+ }
+ error_message = error_map.get(error_message, str(e))
+ return {"error": error_message}
+ finally:
+ p.stop()
diff --git a/services/v1/media/convert/media_convert.py b/services/v1/media/convert/media_convert.py
new file mode 100644
index 0000000000000000000000000000000000000000..4a1816939654c4543e8c3db299ecff2d105bc183
--- /dev/null
+++ b/services/v1/media/convert/media_convert.py
@@ -0,0 +1,145 @@
+# 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 ffmpeg
+import subprocess
+import logging
+from services.file_management import download_file
+from config import LOCAL_STORAGE_PATH
+
+# Set up logging
+logger = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO)
+
+def process_media_convert(media_url, job_id, output_format='mp4', video_codec='libx264', video_preset='medium', video_crf=23, audio_codec='aac', audio_bitrate='128k', webhook_url=None):
+ """
+ Convert media to specified format with customizable encoding settings.
+
+ Args:
+ media_url (str): URL of the media file to convert
+ job_id (str): Unique job identifier
+ output_format (str): Target format (e.g., 'mp4', 'mov', 'mp3', etc.)
+ video_codec (str): Video codec to use (default: 'libx264')
+ video_preset (str): Encoding preset for speed/quality tradeoff (default: 'medium')
+ video_crf (int): Constant Rate Factor for quality (0-51, default: 23)
+ audio_codec (str): Audio codec to use (default: 'aac')
+ audio_bitrate (str): Audio bitrate (default: '128k')
+ webhook_url (str, optional): URL to send completion webhook
+
+ Returns:
+ str: Path to the converted output file
+ """
+ input_filename = download_file(media_url, os.path.join(LOCAL_STORAGE_PATH, f"{job_id}_input"))
+ output_filename = f"{job_id}.{output_format}"
+ output_path = os.path.join(LOCAL_STORAGE_PATH, output_filename)
+
+ try:
+ # Set up the ffmpeg conversion
+ stream = ffmpeg.input(input_filename)
+ output_options = {}
+
+ # Add format if specified
+ if output_format:
+ output_options['format'] = output_format
+
+ # Handle audio-only formats
+ audio_only_formats = ['mp3', 'aac', 'wav', 'flac', 'ogg', 'opus']
+
+ if output_format in audio_only_formats:
+ # Always override the audio codec for audio-only formats
+ # to ensure format compatibility, regardless of what was requested
+ if output_format == 'mp3':
+ audio_codec = 'libmp3lame'
+ elif output_format == 'aac':
+ audio_codec = 'aac'
+ elif output_format == 'opus':
+ audio_codec = 'libopus'
+ elif output_format == 'flac':
+ audio_codec = 'flac'
+ elif output_format == 'ogg':
+ audio_codec = 'libvorbis'
+ elif output_format == 'wav':
+ audio_codec = 'pcm_s16le'
+
+ # For audio-only output, we don't need video codec
+ output_options['acodec'] = audio_codec
+
+ # Use the -vn flag to remove video stream
+ output_options['vn'] = None
+ else:
+ # For video formats, apply both video and audio codec settings
+ output_options['vcodec'] = video_codec
+ output_options['acodec'] = audio_codec
+
+ # Apply additional video encoding options when not using copy
+ if video_codec != 'copy':
+ output_options['preset'] = video_preset
+ output_options['crf'] = str(video_crf)
+
+ # Apply audio bitrate when not using copy
+ if audio_codec != 'copy':
+ output_options['b:a'] = audio_bitrate
+
+ # Configure output
+ stream = ffmpeg.output(stream, output_path, **output_options)
+
+ # Get the ffmpeg command for logging
+ cmd = ffmpeg.compile(stream)
+ logger.info(f"Running ffmpeg command: {' '.join(cmd)}")
+
+ # Run the conversion
+ ffmpeg.run(stream, overwrite_output=True, capture_stdout=True, capture_stderr=True)
+
+ # Clean up input file
+ os.remove(input_filename)
+ logger.info(f"Media conversion successful: {output_path} to format {output_format}")
+
+ # Ensure the output file exists locally before attempting upload
+ if not os.path.exists(output_path):
+ raise FileNotFoundError(f"Output file {output_path} does not exist after conversion.")
+
+ return output_path
+
+ except Exception as e:
+ error_msg = f"Media conversion failed: {str(e)}"
+ logger.error(error_msg)
+
+ # Handle ffmpeg errors specially to provide more context
+ if hasattr(e, 'stderr') and e.stderr:
+ stderr_output = e.stderr.decode('utf-8') if isinstance(e.stderr, bytes) else str(e.stderr)
+ detailed_error = f"FFmpeg error details: {stderr_output}"
+ logger.error(detailed_error)
+ # Raise with combined error info for better debugging
+ raise Exception(f"{error_msg} - {detailed_error}")
+
+ # Clean up input file if it exists
+ if 'input_filename' in locals() and os.path.exists(input_filename):
+ try:
+ os.remove(input_filename)
+ logger.info(f"Cleaned up input file: {input_filename}")
+ except Exception as cleanup_error:
+ logger.error(f"Failed to clean up input file: {str(cleanup_error)}")
+
+ # Clean up output file if it exists
+ if 'output_path' in locals() and os.path.exists(output_path):
+ try:
+ os.remove(output_path)
+ logger.info(f"Cleaned up output file: {output_path}")
+ except Exception as cleanup_error:
+ logger.error(f"Failed to clean up output file: {str(cleanup_error)}")
+
+ raise
\ No newline at end of file
diff --git a/services/v1/media/convert/media_to_mp3.py b/services/v1/media/convert/media_to_mp3.py
new file mode 100644
index 0000000000000000000000000000000000000000..9d6488f0e39441598ed47b02d1cd55ff1014fe1c
--- /dev/null
+++ b/services/v1/media/convert/media_to_mp3.py
@@ -0,0 +1,59 @@
+# 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 ffmpeg
+import requests
+from services.file_management import download_file
+from config import LOCAL_STORAGE_PATH
+
+def process_media_to_mp3(media_url, job_id, bitrate='128k', sample_rate=None):
+ """Convert media to MP3 format with specified bitrate and sample rate."""
+ input_filename = download_file(media_url, os.path.join(LOCAL_STORAGE_PATH, f"{job_id}_input"))
+ output_filename = f"{job_id}.mp3"
+ output_path = os.path.join(LOCAL_STORAGE_PATH, output_filename)
+
+ try:
+ # Build the ffmpeg command
+ stream = ffmpeg.input(input_filename)
+ output_options = {'acodec': 'libmp3lame', 'audio_bitrate': bitrate}
+
+ # Only set sample rate if provided
+ if sample_rate is not None:
+ output_options['ar'] = sample_rate
+
+ # Convert media file to MP3 with specified options
+ (
+ stream
+ .output(output_path, **output_options)
+ .overwrite_output()
+ .run(capture_stdout=True, capture_stderr=True)
+ )
+ os.remove(input_filename)
+ sample_rate_info = f" and sample rate {sample_rate}Hz" if sample_rate is not None else ""
+ print(f"Conversion successful: {output_path} with bitrate {bitrate}{sample_rate_info}")
+
+ # Ensure the output file exists locally before attempting upload
+ if not os.path.exists(output_path):
+ raise FileNotFoundError(f"Output file {output_path} does not exist after conversion.")
+
+ return output_path
+
+ except Exception as e:
+ print(f"Conversion failed: {str(e)}")
+ raise
diff --git a/services/v1/media/feedback/__init__.py b/services/v1/media/feedback/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..4b428a687502a4b00dcb5b935568db8b899237a6
--- /dev/null
+++ b/services/v1/media/feedback/__init__.py
@@ -0,0 +1 @@
+# Media feedback package
\ No newline at end of file
diff --git a/services/v1/media/feedback/feedback.py b/services/v1/media/feedback/feedback.py
new file mode 100644
index 0000000000000000000000000000000000000000..02c0cda610fd89f21e1b4678edf7cc87c9c0f541
--- /dev/null
+++ b/services/v1/media/feedback/feedback.py
@@ -0,0 +1,16 @@
+import os
+
+def get_feedback_path():
+ """
+ Returns the absolute path to the feedback static files directory
+ """
+ # Define the path to the static feedback site files
+ # Keeping files isolated in the feedback module directory
+ base_dir = os.path.dirname(os.path.abspath(__file__))
+ static_dir = os.path.join(base_dir, 'static')
+
+ # Create the directory if it doesn't exist
+ if not os.path.exists(static_dir):
+ os.makedirs(static_dir)
+
+ return static_dir
diff --git a/services/v1/media/feedback/static/404.html b/services/v1/media/feedback/static/404.html
new file mode 100644
index 0000000000000000000000000000000000000000..30962bf88549a6aa3fb77a8471f90c96b729c701
--- /dev/null
+++ b/services/v1/media/feedback/static/404.html
@@ -0,0 +1 @@
+404: This page could not be found.Feedback Magic v1.0
404
This page could not be found.
\ No newline at end of file
diff --git a/services/v1/media/feedback/static/_next/static/IKZmjEopX3I__YqoGlhxM/_buildManifest.js b/services/v1/media/feedback/static/_next/static/IKZmjEopX3I__YqoGlhxM/_buildManifest.js
new file mode 100644
index 0000000000000000000000000000000000000000..9ed79f5438f09e3dc67b7286e35d895c358df009
--- /dev/null
+++ b/services/v1/media/feedback/static/_next/static/IKZmjEopX3I__YqoGlhxM/_buildManifest.js
@@ -0,0 +1 @@
+self.__BUILD_MANIFEST=function(e,r,t){return{__rewrites:{afterFiles:[],beforeFiles:[],fallback:[]},__routerFilterStatic:{numItems:3,errorRate:1e-4,numBits:58,numHashes:14,bitArray:[1,1,0,e,0,e,e,r,e,e,r,e,e,e,r,e,r,r,e,r,r,r,e,r,r,r,r,r,e,r,e,e,e,e,r,e,e,r,e,e,e,r,e,r,e,r,r,e,e,e,r,r,e,e,e,r,e,e]},__routerFilterDynamic:{numItems:r,errorRate:1e-4,numBits:r,numHashes:null,bitArray:[]},"/_error":["static/chunks/pages/_error-5933f280f2bada68.js"],sortedPages:["/_app","/_error"]}}(1,0,1e-4),self.__BUILD_MANIFEST_CB&&self.__BUILD_MANIFEST_CB();
\ No newline at end of file
diff --git a/services/v1/media/feedback/static/_next/static/IKZmjEopX3I__YqoGlhxM/_ssgManifest.js b/services/v1/media/feedback/static/_next/static/IKZmjEopX3I__YqoGlhxM/_ssgManifest.js
new file mode 100644
index 0000000000000000000000000000000000000000..5b3ff592fd46c8736892a12864fdf3fed8775202
--- /dev/null
+++ b/services/v1/media/feedback/static/_next/static/IKZmjEopX3I__YqoGlhxM/_ssgManifest.js
@@ -0,0 +1 @@
+self.__SSG_MANIFEST=new Set([]);self.__SSG_MANIFEST_CB&&self.__SSG_MANIFEST_CB()
\ No newline at end of file
diff --git a/services/v1/media/feedback/static/_next/static/chunks/0b465130-17d112986620d03b.js b/services/v1/media/feedback/static/_next/static/chunks/0b465130-17d112986620d03b.js
new file mode 100644
index 0000000000000000000000000000000000000000..125edd15be6a2186c8f40d63b7b5212ba65cd0ff
--- /dev/null
+++ b/services/v1/media/feedback/static/_next/static/chunks/0b465130-17d112986620d03b.js
@@ -0,0 +1 @@
+"use strict";(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[776],{4787:(t,e,i)=>{let r,s,n;function o(t,e,i){var r;return(e="symbol"==typeof(r=function(t,e){if("object"!=typeof t||!t)return t;var i=t[Symbol.toPrimitive];if(void 0!==i){var r=i.call(t,e||"default");if("object"!=typeof r)return r;throw TypeError("@@toPrimitive must return a primitive value.")}return("string"===e?String:Number)(t)}(e,"string"))?r:r+"")in t?Object.defineProperty(t,e,{value:i,enumerable:!0,configurable:!0,writable:!0}):t[e]=i,t}function a(t,e){var i=Object.keys(t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(t);e&&(r=r.filter(function(e){return Object.getOwnPropertyDescriptor(t,e).enumerable})),i.push.apply(i,r)}return i}function l(t){for(var e=1;e=0)continue;i[r]=t[r]}return i}(t,e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(t);for(r=0;r=0||({}).propertyIsEnumerable.call(t,i)&&(s[i]=t[i])}return s}function c(t,e){return e||(e=t.slice(0)),Object.freeze(Object.defineProperties(t,{raw:{value:Object.freeze(e)}}))}i.d(e,{Hl:()=>sw,mW:()=>sH});class u{constructor(){o(this,"browserShadowBlurConstant",1),o(this,"DPI",96),o(this,"devicePixelRatio","undefined"!=typeof window?window.devicePixelRatio:1),o(this,"perfLimitSizeTotal",2097152),o(this,"maxCacheSideLimit",4096),o(this,"minCacheSideLimit",256),o(this,"disableStyleCopyPaste",!1),o(this,"enableGLFiltering",!0),o(this,"textureSize",4096),o(this,"forceGLPutImageData",!1),o(this,"cachesBoundsOfCurve",!1),o(this,"fontPaths",{}),o(this,"NUM_FRACTION_DIGITS",4)}}let d=new class extends u{constructor(t){super(),this.configure(t)}configure(){let t=arguments.length>0&&void 0!==arguments[0]?arguments[0]:{};Object.assign(this,t)}addFonts(){let t=arguments.length>0&&void 0!==arguments[0]?arguments[0]:{};this.fontPaths=l(l({},this.fontPaths),t)}removeFonts(){(arguments.length>0&&void 0!==arguments[0]?arguments[0]:[]).forEach(t=>{delete this.fontPaths[t]})}clearFonts(){this.fontPaths={}}restoreDefaults(t){let e=new u,i=(null==t?void 0:t.reduce((t,i)=>(t[i]=e[i],t),{}))||e;this.configure(i)}},g=function(t){for(var e=arguments.length,i=Array(e>1?e-1:0),r=1;rthis.testPrecision(e,t)),e.getExtension("WEBGL_lose_context").loseContext(),g("log","WebGL: max texture size ".concat(this.maxTextureSize)))}isSupported(t){return!!this.maxTextureSize&&this.maxTextureSize>=t}}let _={},y=()=>r||(r={document:document,window:window,isTouchSupported:"ontouchstart"in window||"ontouchstart"in document||window&&window.navigator&&window.navigator.maxTouchPoints>0,WebGLProbe:new v,dispose(){},copyPasteData:_}),x=()=>y().document,C=()=>y().window,b=()=>{var t;return Math.max(null!==(t=d.devicePixelRatio)&&void 0!==t?t:C().devicePixelRatio,1)},S=new class{constructor(){o(this,"charWidthsCache",{}),o(this,"boundsOfCurveCache",{})}getFontCache(t){let{fontFamily:e,fontStyle:i,fontWeight:r}=t;e=e.toLowerCase(),this.charWidthsCache[e]||(this.charWidthsCache[e]={});let s=this.charWidthsCache[e],n="".concat(i.toLowerCase(),"_").concat((r+"").toLowerCase());return s[n]||(s[n]={}),s[n]}clearFontCache(t){(t=(t||"").toLowerCase())?this.charWidthsCache[t]&&delete this.charWidthsCache[t]:this.charWidthsCache={}}limitDimsByArea(t){let{perfLimitSizeTotal:e}=d,i=Math.sqrt(e*t);return[Math.floor(i),Math.floor(e/i)]}},w="6.6.1";function T(){}let O=Math.PI/2,D=2*Math.PI,k=Math.PI/180,M=Object.freeze([1,0,0,1,0,0]),E="center",P="left",A="bottom",j="right",F="none",L=/\r?\n/,R="moving",I="scaling",B="rotating",X="rotate",Y="skewing",W="resizing",V="modifyPoly",H="changed",z="scale",G="scaleX",N="scaleY",U="skewX",q="skewY",K="fill",J="stroke",Q="modified",Z="json",$=new class{constructor(){this[Z]=new Map,this.svg=new Map}has(t){return this[Z].has(t)}getClass(t){let e=this[Z].get(t);if(!e)throw new f("No class registered for ".concat(t));return e}setClass(t,e){e?this[Z].set(e,t):(this[Z].set(t.type,t),this[Z].set(t.type.toLowerCase(),t))}getSVGClass(t){return this.svg.get(t)}setSVGClass(t,e){this.svg.set(null!=e?e:t.type.toLowerCase(),t)}},tt=new class extends Array{remove(t){let e=this.indexOf(t);e>-1&&this.splice(e,1)}cancelAll(){let t=this.splice(0);return t.forEach(t=>t.abort()),t}cancelByCanvas(t){if(!t)return[];let e=this.filter(e=>{var i;return e.target===t||"object"==typeof e.target&&(null===(i=e.target)||void 0===i?void 0:i.canvas)===t});return e.forEach(t=>t.abort()),e}cancelByTarget(t){if(!t)return[];let e=this.filter(e=>e.target===t);return e.forEach(t=>t.abort()),e}};class te{constructor(){o(this,"__eventListeners",{})}on(t,e){return(this.__eventListeners||(this.__eventListeners={}),"object"==typeof t)?(Object.entries(t).forEach(t=>{let[e,i]=t;this.on(e,i)}),()=>this.off(t)):e?(this.__eventListeners[t]||(this.__eventListeners[t]=[]),this.__eventListeners[t].push(e),()=>this.off(t,e)):()=>!1}once(t,e){if("object"==typeof t){let e=[];return Object.entries(t).forEach(t=>{let[i,r]=t;e.push(this.once(i,r))}),()=>e.forEach(t=>t())}if(e){let i=this.on(t,function(){for(var t=arguments.length,r=Array(t),s=0;s!1}_removeEventListener(t,e){if(this.__eventListeners[t]){if(e){let i=this.__eventListeners[t],r=i.indexOf(e);r>-1&&i.splice(r,1)}else this.__eventListeners[t]=[]}}off(t,e){if(this.__eventListeners){if(void 0===t)for(let t in this.__eventListeners)this._removeEventListener(t);else"object"==typeof t?Object.entries(t).forEach(t=>{let[e,i]=t;this._removeEventListener(e,i)}):this._removeEventListener(t,e)}}fire(t,e){var i;if(!this.__eventListeners)return;let r=null===(i=this.__eventListeners[t])||void 0===i?void 0:i.concat();if(r)for(let t=0;t{let i=t.indexOf(e);return -1!==i&&t.splice(i,1),t},tr=t=>{if(0===t)return 1;switch(Math.abs(t)/O){case 1:case 3:return 0;case 2:return -1}return Math.cos(t)},ts=t=>{if(0===t)return 0;let e=Math.sign(t);switch(t/O){case 1:return e;case 2:return 0;case 3:return-e}return Math.sin(t)};class tn{constructor(){let t=arguments.length>0&&void 0!==arguments[0]?arguments[0]:0,e=arguments.length>1&&void 0!==arguments[1]?arguments[1]:0;"object"==typeof t?(this.x=t.x,this.y=t.y):(this.x=t,this.y=e)}add(t){return new tn(this.x+t.x,this.y+t.y)}addEquals(t){return this.x+=t.x,this.y+=t.y,this}scalarAdd(t){return new tn(this.x+t,this.y+t)}scalarAddEquals(t){return this.x+=t,this.y+=t,this}subtract(t){return new tn(this.x-t.x,this.y-t.y)}subtractEquals(t){return this.x-=t.x,this.y-=t.y,this}scalarSubtract(t){return new tn(this.x-t,this.y-t)}scalarSubtractEquals(t){return this.x-=t,this.y-=t,this}multiply(t){return new tn(this.x*t.x,this.y*t.y)}scalarMultiply(t){return new tn(this.x*t,this.y*t)}scalarMultiplyEquals(t){return this.x*=t,this.y*=t,this}divide(t){return new tn(this.x/t.x,this.y/t.y)}scalarDivide(t){return new tn(this.x/t,this.y/t)}scalarDivideEquals(t){return this.x/=t,this.y/=t,this}eq(t){return this.x===t.x&&this.y===t.y}lt(t){return this.xt.x&&this.y>t.y}gte(t){return this.x>=t.x&&this.y>=t.y}lerp(t){let e=arguments.length>1&&void 0!==arguments[1]?arguments[1]:.5;return e=Math.max(Math.min(1,e),0),new tn(this.x+(t.x-this.x)*e,this.y+(t.y-this.y)*e)}distanceFrom(t){let e=this.x-t.x,i=this.y-t.y;return Math.sqrt(e*e+i*i)}midPointFrom(t){return this.lerp(t)}min(t){return new tn(Math.min(this.x,t.x),Math.min(this.y,t.y))}max(t){return new tn(Math.max(this.x,t.x),Math.max(this.y,t.y))}toString(){return"".concat(this.x,",").concat(this.y)}setXY(t,e){return this.x=t,this.y=e,this}setX(t){return this.x=t,this}setY(t){return this.y=t,this}setFromPoint(t){return this.x=t.x,this.y=t.y,this}swap(t){let e=this.x,i=this.y;this.x=t.x,this.y=t.y,t.x=e,t.y=i}clone(){return new tn(this.x,this.y)}rotate(t){let e=arguments.length>1&&void 0!==arguments[1]?arguments[1]:to,i=ts(t),r=tr(t),s=this.subtract(e);return new tn(s.x*r-s.y*i,s.x*i+s.y*r).add(e)}transform(t){let e=arguments.length>1&&void 0!==arguments[1]&&arguments[1];return new tn(t[0]*this.x+t[2]*this.y+(e?0:t[4]),t[1]*this.x+t[3]*this.y+(e?0:t[5]))}}let to=new tn(0,0),ta=t=>!!t&&Array.isArray(t._objects);function tl(t){class e extends t{constructor(){super(...arguments),o(this,"_objects",[])}_onObjectAdded(t){}_onObjectRemoved(t){}_onStackOrderChanged(t){}add(){for(var t=arguments.length,e=Array(t),i=0;ithis._onObjectAdded(t)),r}insertAt(t){for(var e=arguments.length,i=Array(e>1?e-1:0),r=1;rthis._onObjectAdded(t)),this._objects.length}remove(){let t=this._objects,e=[];for(var i=arguments.length,r=Array(i),s=0;s{let r=t.indexOf(i);-1!==r&&(t.splice(r,1),e.push(i),this._onObjectRemoved(i))}),e}forEachObject(t){this.getObjects().forEach((e,i,r)=>t(e,i,r))}getObjects(){for(var t=arguments.length,e=Array(t),i=0;it.isType(...e))}item(t){return this._objects[t]}isEmpty(){return 0===this._objects.length}size(){return this._objects.length}contains(t,i){return!!this._objects.includes(t)||!!i&&this._objects.some(i=>i instanceof e&&i.contains(t,!0))}complexity(){return this._objects.reduce((t,e)=>t+=e.complexity?e.complexity():0,0)}sendObjectToBack(t){return!(!t||t===this._objects[0])&&(ti(this._objects,t),this._objects.unshift(t),this._onStackOrderChanged(t),!0)}bringObjectToFront(t){return!(!t||t===this._objects[this._objects.length-1])&&(ti(this._objects,t),this._objects.push(t),this._onStackOrderChanged(t),!0)}sendObjectBackwards(t,e){if(!t)return!1;let i=this._objects.indexOf(t);if(0!==i){let r=this.findNewLowerIndex(t,i,e);return ti(this._objects,t),this._objects.splice(r,0,t),this._onStackOrderChanged(t),!0}return!1}bringObjectForward(t,e){if(!t)return!1;let i=this._objects.indexOf(t);if(i!==this._objects.length-1){let r=this.findNewUpperIndex(t,i,e);return ti(this._objects,t),this._objects.splice(r,0,t),this._onStackOrderChanged(t),!0}return!1}moveObjectTo(t,e){return t!==this._objects[e]&&(ti(this._objects,t),this._objects.splice(e,0,t),this._onStackOrderChanged(t),!0)}findNewLowerIndex(t,e,i){let r;if(i){r=e;for(let i=e-1;i>=0;--i)if(t.isOverlapping(this._objects[i])){r=i;break}}else r=e-1;return r}findNewUpperIndex(t,e,i){let r;if(i){r=e;for(let i=e+1;i1&&void 0!==arguments[1]?arguments[1]:{},o=[],a=new tn(e,i),l=a.add(new tn(r,s));for(let t=this._objects.length-1;t>=0;t--){let e=this._objects[t];e.selectable&&e.visible&&(n&&e.intersectsWithRect(a,l)||e.isContainedWithinRect(a,l)||n&&e.containsPoint(a)||n&&e.containsPoint(l))&&o.push(e)}return o}}return e}class th extends te{_setOptions(){let t=arguments.length>0&&void 0!==arguments[0]?arguments[0]:{};for(let e in t)this.set(e,t[e])}_setObject(t){for(let e in t)this._set(e,t[e])}set(t,e){return"object"==typeof t?this._setObject(t):this._set(t,e),this}_set(t,e){this[t]=e}toggle(t){let e=this.get(t);return"boolean"==typeof e&&this.set(t,!e),this}get(t){return this[t]}}function tc(t){return C().requestAnimationFrame(t)}function tu(t){return C().cancelAnimationFrame(t)}let td=0,tg=()=>td++,tf=()=>{let t=x().createElement("canvas");if(!t||void 0===t.getContext)throw new f("Failed to create `canvas` element");return t},tp=()=>x().createElement("img"),tm=t=>{let e=tf();return e.width=t.width,e.height=t.height,e},tv=(t,e,i)=>t.toDataURL("image/".concat(e),i),t_=(t,e,i)=>new Promise((r,s)=>{t.toBlob(r,"image/".concat(e),i)}),ty=t=>t*k,tx=t=>t/k,tC=t=>t.every((t,e)=>t===M[e]),tb=(t,e,i)=>new tn(t).transform(e,i),tS=t=>{let e=1/(t[0]*t[3]-t[1]*t[2]),i=[e*t[3],-e*t[1],-e*t[2],e*t[0],0,0],{x:r,y:s}=new tn(t[4],t[5]).transform(i,!0);return i[4]=-r,i[5]=-s,i},tw=(t,e,i)=>[t[0]*e[0]+t[2]*e[1],t[1]*e[0]+t[3]*e[1],t[0]*e[2]+t[2]*e[3],t[1]*e[2]+t[3]*e[3],i?0:t[0]*e[4]+t[2]*e[5]+t[4],i?0:t[1]*e[4]+t[3]*e[5]+t[5]],tT=(t,e)=>t.reduceRight((t,i)=>i&&t?tw(i,t,e):i||t,void 0)||M.concat(),tO=t=>{let[e,i]=t;return Math.atan2(i,e)},tD=t=>{let e=tO(t),i=Math.pow(t[0],2)+Math.pow(t[1],2),r=Math.sqrt(i),s=(t[0]*t[3]-t[2]*t[1])/r,n=Math.atan2(t[0]*t[2]+t[1]*t[3],i);return{angle:tx(e),scaleX:r,scaleY:s,skewX:tx(n),skewY:0,translateX:t[4]||0,translateY:t[5]||0}},tk=function(t){return[1,0,0,1,t,arguments.length>1&&void 0!==arguments[1]?arguments[1]:0]};function tM(){let{angle:t=0}=arguments.length>0&&void 0!==arguments[0]?arguments[0]:{},{x:e=0,y:i=0}=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{},r=ty(t),s=tr(r),n=ts(r);return[s,n,-n,s,e?e-(s*e-n*i):0,i?i-(n*e+s*i):0]}let tE=function(t){return[t,0,0,arguments.length>1&&void 0!==arguments[1]?arguments[1]:t,0,0]},tP=t=>Math.tan(ty(t)),tA=t=>[1,0,tP(t),1,0,0],tj=t=>[1,tP(t),0,1,0,0],tF=t=>{let{scaleX:e=1,scaleY:i=1,flipX:r=!1,flipY:s=!1,skewX:n=0,skewY:o=0}=t,a=tE(r?-e:e,s?-i:i);return n&&(a=tw(a,tA(n),!0)),o&&(a=tw(a,tj(o),!0)),a},tL=t=>{let{translateX:e=0,translateY:i=0,angle:r=0}=t,s=tk(e,i);r&&(s=tw(s,tM({angle:r})));let n=tF(t);return tC(n)||(s=tw(s,n)),s},tR=function(t){let{signal:e,crossOrigin:i=null}=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{};return new Promise(function(r,s){let n;if(e&&e.aborted)return s(new p("loadImage"));let o=tp();e&&(n=function(t){o.src="",s(t)},e.addEventListener("abort",n,{once:!0}));let a=function(){o.onload=o.onerror=null,n&&(null==e||e.removeEventListener("abort",n)),r(o)};t?(o.onload=a,o.onerror=function(){n&&(null==e||e.removeEventListener("abort",n)),s(new f("Error loading ".concat(o.src)))},i&&(o.crossOrigin=i),o.src=t):a()})},tI=function(t){let{signal:e,reviver:i=T}=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{};return new Promise((r,s)=>{let n=[];e&&e.addEventListener("abort",s,{once:!0}),Promise.all(t.map(t=>$.getClass(t.type).fromObject(t,{signal:e}).then(e=>(i(t,e),n.push(e),e)))).then(r).catch(t=>{n.forEach(t=>{t.dispose&&t.dispose()}),s(t)}).finally(()=>{e&&e.removeEventListener("abort",s)})})},tB=function(t){let{signal:e}=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{};return new Promise((i,r)=>{let s=[];e&&e.addEventListener("abort",r,{once:!0});let n=Object.values(t).map(t=>t&&t.type&&$.has(t.type)?tI([t],{signal:e}).then(t=>{let[e]=t;return s.push(e),e}):t),o=Object.keys(t);Promise.all(n).then(t=>t.reduce((t,e,i)=>(t[o[i]]=e,t),{})).then(i).catch(t=>{s.forEach(t=>{t.dispose&&t.dispose()}),r(t)}).finally(()=>{e&&e.removeEventListener("abort",r)})})},tX=function(t){return(arguments.length>1&&void 0!==arguments[1]?arguments[1]:[]).reduce((e,i)=>(i in t&&(e[i]=t[i]),e),{})},tY=(t,e)=>Object.keys(t).reduce((i,r)=>(e(t[r],r,t)&&(i[r]=t[r]),i),{}),tW={aliceblue:"#F0F8FF",antiquewhite:"#FAEBD7",aqua:"#0FF",aquamarine:"#7FFFD4",azure:"#F0FFFF",beige:"#F5F5DC",bisque:"#FFE4C4",black:"#000",blanchedalmond:"#FFEBCD",blue:"#00F",blueviolet:"#8A2BE2",brown:"#A52A2A",burlywood:"#DEB887",cadetblue:"#5F9EA0",chartreuse:"#7FFF00",chocolate:"#D2691E",coral:"#FF7F50",cornflowerblue:"#6495ED",cornsilk:"#FFF8DC",crimson:"#DC143C",cyan:"#0FF",darkblue:"#00008B",darkcyan:"#008B8B",darkgoldenrod:"#B8860B",darkgray:"#A9A9A9",darkgrey:"#A9A9A9",darkgreen:"#006400",darkkhaki:"#BDB76B",darkmagenta:"#8B008B",darkolivegreen:"#556B2F",darkorange:"#FF8C00",darkorchid:"#9932CC",darkred:"#8B0000",darksalmon:"#E9967A",darkseagreen:"#8FBC8F",darkslateblue:"#483D8B",darkslategray:"#2F4F4F",darkslategrey:"#2F4F4F",darkturquoise:"#00CED1",darkviolet:"#9400D3",deeppink:"#FF1493",deepskyblue:"#00BFFF",dimgray:"#696969",dimgrey:"#696969",dodgerblue:"#1E90FF",firebrick:"#B22222",floralwhite:"#FFFAF0",forestgreen:"#228B22",fuchsia:"#F0F",gainsboro:"#DCDCDC",ghostwhite:"#F8F8FF",gold:"#FFD700",goldenrod:"#DAA520",gray:"#808080",grey:"#808080",green:"#008000",greenyellow:"#ADFF2F",honeydew:"#F0FFF0",hotpink:"#FF69B4",indianred:"#CD5C5C",indigo:"#4B0082",ivory:"#FFFFF0",khaki:"#F0E68C",lavender:"#E6E6FA",lavenderblush:"#FFF0F5",lawngreen:"#7CFC00",lemonchiffon:"#FFFACD",lightblue:"#ADD8E6",lightcoral:"#F08080",lightcyan:"#E0FFFF",lightgoldenrodyellow:"#FAFAD2",lightgray:"#D3D3D3",lightgrey:"#D3D3D3",lightgreen:"#90EE90",lightpink:"#FFB6C1",lightsalmon:"#FFA07A",lightseagreen:"#20B2AA",lightskyblue:"#87CEFA",lightslategray:"#789",lightslategrey:"#789",lightsteelblue:"#B0C4DE",lightyellow:"#FFFFE0",lime:"#0F0",limegreen:"#32CD32",linen:"#FAF0E6",magenta:"#F0F",maroon:"#800000",mediumaquamarine:"#66CDAA",mediumblue:"#0000CD",mediumorchid:"#BA55D3",mediumpurple:"#9370DB",mediumseagreen:"#3CB371",mediumslateblue:"#7B68EE",mediumspringgreen:"#00FA9A",mediumturquoise:"#48D1CC",mediumvioletred:"#C71585",midnightblue:"#191970",mintcream:"#F5FFFA",mistyrose:"#FFE4E1",moccasin:"#FFE4B5",navajowhite:"#FFDEAD",navy:"#000080",oldlace:"#FDF5E6",olive:"#808000",olivedrab:"#6B8E23",orange:"#FFA500",orangered:"#FF4500",orchid:"#DA70D6",palegoldenrod:"#EEE8AA",palegreen:"#98FB98",paleturquoise:"#AFEEEE",palevioletred:"#DB7093",papayawhip:"#FFEFD5",peachpuff:"#FFDAB9",peru:"#CD853F",pink:"#FFC0CB",plum:"#DDA0DD",powderblue:"#B0E0E6",purple:"#800080",rebeccapurple:"#639",red:"#F00",rosybrown:"#BC8F8F",royalblue:"#4169E1",saddlebrown:"#8B4513",salmon:"#FA8072",sandybrown:"#F4A460",seagreen:"#2E8B57",seashell:"#FFF5EE",sienna:"#A0522D",silver:"#C0C0C0",skyblue:"#87CEEB",slateblue:"#6A5ACD",slategray:"#708090",slategrey:"#708090",snow:"#FFFAFA",springgreen:"#00FF7F",steelblue:"#4682B4",tan:"#D2B48C",teal:"#008080",thistle:"#D8BFD8",tomato:"#FF6347",turquoise:"#40E0D0",violet:"#EE82EE",wheat:"#F5DEB3",white:"#FFF",whitesmoke:"#F5F5F5",yellow:"#FF0",yellowgreen:"#9ACD32"},tV=(t,e,i)=>(i<0&&(i+=1),i>1&&(i-=1),i<1/6?t+6*(e-t)*i:i<.5?e:i<2/3?t+(e-t)*(2/3-i)*6:t),tH=(t,e,i,r)=>{let s,n;t/=255;let o=Math.max(t,e/=255,i/=255),a=Math.min(t,e,i),l=(o+a)/2;if(o===a)s=n=0;else{let r=o-a;switch(n=l>.5?r/(2-o-a):r/(o+a),o){case t:s=(e-i)/r+6*(e0&&void 0!==arguments[0]?arguments[0]:"1";return parseFloat(t)/(t.endsWith("%")?100:1)},tG=t=>Math.min(Math.round(t),255).toString(16).toUpperCase().padStart(2,"0"),tN=t=>{let[e,i,r,s=1]=t,n=Math.round(.3*e+.59*i+.11*r);return[n,n,n,s]};class tU{constructor(t){if(o(this,"isUnrecognised",!1),t){if(t instanceof tU)this.setSource([...t._source]);else if(Array.isArray(t)){let[e,i,r,s=1]=t;this.setSource([e,i,r,s])}else this.setSource(this._tryParsingColor(t))}else this.setSource([0,0,0,1])}_tryParsingColor(t){return(t=t.toLowerCase())in tW&&(t=tW[t]),"transparent"===t?[255,255,255,0]:tU.sourceFromHex(t)||tU.sourceFromRgb(t)||tU.sourceFromHsl(t)||(this.isUnrecognised=!0,[0,0,0,1])}getSource(){return this._source}setSource(t){this._source=t}toRgb(){let[t,e,i]=this.getSource();return"rgb(".concat(t,",").concat(e,",").concat(i,")")}toRgba(){return"rgba(".concat(this.getSource().join(","),")")}toHsl(){let[t,e,i]=tH(...this.getSource());return"hsl(".concat(t,",").concat(e,"%,").concat(i,"%)")}toHsla(){let[t,e,i,r]=tH(...this.getSource());return"hsla(".concat(t,",").concat(e,"%,").concat(i,"%,").concat(r,")")}toHex(){return this.toHexa().slice(0,6)}toHexa(){let[t,e,i,r]=this.getSource();return"".concat(tG(t)).concat(tG(e)).concat(tG(i)).concat(tG(Math.round(255*r)))}getAlpha(){return this.getSource()[3]}setAlpha(t){return this._source[3]=t,this}toGrayscale(){return this.setSource(tN(this.getSource())),this}toBlackWhite(t){let[e,,,i]=tN(this.getSource()),r=e<(t||127)?0:255;return this.setSource([r,r,r,i]),this}overlayWith(t){t instanceof tU||(t=new tU(t));let e=this.getSource(),i=t.getSource(),[r,s,n]=e.map((t,e)=>Math.round(.5*t+.5*i[e]));return this.setSource([r,s,n,e[3]]),this}static fromRgb(t){return tU.fromRgba(t)}static fromRgba(t){return new tU(tU.sourceFromRgb(t))}static sourceFromRgb(t){let e=t.match(/^rgba?\(\s*(\d{0,3}(?:\.\d+)?%?)\s*[\s|,]\s*(\d{0,3}(?:\.\d+)?%?)\s*[\s|,]\s*(\d{0,3}(?:\.\d+)?%?)\s*(?:\s*[,/]\s*(\d{0,3}(?:\.\d+)?%?)\s*)?\)$/i);if(e){let[t,i,r]=e.slice(1,4).map(t=>{let e=parseFloat(t);return t.endsWith("%")?Math.round(2.55*e):e});return[t,i,r,tz(e[4])]}}static fromHsl(t){return tU.fromHsla(t)}static fromHsla(t){return new tU(tU.sourceFromHsl(t))}static sourceFromHsl(t){let e,i,r;let s=t.match(/^hsla?\(\s*([+-]?\d{0,3}(?:\.\d+)?(?:deg|turn|rad)?)\s*[\s|,]\s*(\d{0,3}(?:\.\d+)?%?)\s*[\s|,]\s*(\d{0,3}(?:\.\d+)?%?)\s*(?:\s*[,/]\s*(\d*(?:\.\d+)?%?)\s*)?\)$/i);if(!s)return;let n=(tU.parseAngletoDegrees(s[1])%360+360)%360/360,o=parseFloat(s[2])/100,a=parseFloat(s[3])/100;if(0===o)e=i=r=a;else{let t=a<=.5?a*(o+1):a+o-a*o,s=2*a-t;e=tV(s,t,n+1/3),i=tV(s,t,n),r=tV(s,t,n-1/3)}return[Math.round(255*e),Math.round(255*i),Math.round(255*r),tz(s[4])]}static fromHex(t){return new tU(tU.sourceFromHex(t))}static sourceFromHex(t){if(t.match(/^#?(([0-9a-f]){3,4}|([0-9a-f]{2}){3,4})$/i)){let e=t.slice(t.indexOf("#")+1),[i,r,s,n=255]=(e.length<=4?e.split("").map(t=>t+t):e.match(/.{2}/g)).map(t=>parseInt(t,16));return[i,r,s,n/255]}}static parseAngletoDegrees(t){let e=t.toLowerCase(),i=parseFloat(e);return e.includes("rad")?tx(i):e.includes("turn")?360*i:i}}let tq=(t,e)=>parseFloat(Number(t).toFixed(e)),tK=function(t){let e=arguments.length>1&&void 0!==arguments[1]?arguments[1]:16,i=/\D{0,2}$/.exec(t),r=parseFloat(t),s=d.DPI;switch(null==i?void 0:i[0]){case"mm":return r*s/25.4;case"cm":return r*s/2.54;case"in":return r*s;case"pt":return r*s/72;case"pc":return r*s/72*12;case"em":return r*e;default:return r}},tJ=t=>{let[e,i]=t.trim().split(" "),[r,s]=e&&e!==F?[e.slice(1,4),e.slice(5,8)]:e===F?[e,e]:["Mid","Mid"];return{meetOrSlice:i||"meet",alignX:r,alignY:s}},tQ=t=>"matrix("+t.map(t=>tq(t,d.NUM_FRACTION_DIGITS)).join(" ")+")",tZ=function(t,e){let i,r,s=!(arguments.length>2&&void 0!==arguments[2])||arguments[2];if(e){if(e.toLive)i="url(#SVGID_".concat(e.id,")");else{let t=new tU(e),s=t.getAlpha();i=t.toRgb(),1!==s&&(r=s.toString())}}else i="none";return s?"".concat(t,": ").concat(i,"; ").concat(r?"".concat(t,"-opacity: ").concat(r,"; "):""):"".concat(t,'="').concat(i,'" ').concat(r?"".concat(t,'-opacity="').concat(r,'" '):"")},t$=t=>!!t&&void 0!==t.toLive,t0=t=>!!t&&"function"==typeof t.toObject,t1=t=>!!t&&void 0!==t.offsetX&&"source"in t,t2=t=>!!t&&"multiSelectionStacking"in t;function t5(t){let e=t&&t3(t),i=0,r=0;if(!t||!e)return{left:i,top:r};let s=t,n=e.documentElement,o=e.body||{scrollLeft:0,scrollTop:0};for(;s&&(s.parentNode||s.host)&&((s=s.parentNode||s.host)===e?(i=o.scrollLeft||n.scrollLeft||0,r=o.scrollTop||n.scrollTop||0):(i+=s.scrollLeft||0,r+=s.scrollTop||0),1!==s.nodeType||"fixed"!==s.style.position););return{left:i,top:r}}let t3=t=>t.ownerDocument||null,t4=t=>{var e;return(null===(e=t.ownerDocument)||void 0===e?void 0:e.defaultView)||null},t8=function(t,e,i){let{width:r,height:s}=i,n=arguments.length>3&&void 0!==arguments[3]?arguments[3]:1;t.width=r,t.height=s,n>1&&(t.setAttribute("width",(r*n).toString()),t.setAttribute("height",(s*n).toString()),e.scale(n,n))},t6=(t,e)=>{let{width:i,height:r}=e;i&&(t.style.width="number"==typeof i?"".concat(i,"px"):i),r&&(t.style.height="number"==typeof r?"".concat(r,"px"):r)};function t9(t){return void 0!==t.onselectstart&&(t.onselectstart=()=>!1),t.style.userSelect=F,t}class t7{constructor(t){o(this,"_originalCanvasStyle",void 0),o(this,"lower",void 0);let e=this.createLowerCanvas(t);this.lower={el:e,ctx:e.getContext("2d")}}createLowerCanvas(t){let e=t&&void 0!==t.getContext?t:t&&x().getElementById(t)||tf();if(e.hasAttribute("data-fabric"))throw new f("Trying to initialize a canvas that has already been initialized. Did you forget to dispose the canvas?");return this._originalCanvasStyle=e.style.cssText,e.setAttribute("data-fabric","main"),e.classList.add("lower-canvas"),e}cleanupDOM(t){let{width:e,height:i}=t,{el:r}=this.lower;r.classList.remove("lower-canvas"),r.removeAttribute("data-fabric"),r.setAttribute("width","".concat(e)),r.setAttribute("height","".concat(i)),r.style.cssText=this._originalCanvasStyle||"",this._originalCanvasStyle=void 0}setDimensions(t,e){let{el:i,ctx:r}=this.lower;t8(i,r,t,e)}setCSSDimensions(t){t6(this.lower.el,t)}calcOffset(){return function(t){var e;let i=t&&t3(t),r={left:0,top:0};if(!i)return r;let s=(null===(e=t4(t))||void 0===e?void 0:e.getComputedStyle(t,null))||{};r.left+=parseInt(s.borderLeftWidth,10)||0,r.top+=parseInt(s.borderTopWidth,10)||0,r.left+=parseInt(s.paddingLeft,10)||0,r.top+=parseInt(s.paddingTop,10)||0;let n={left:0,top:0},o=i.documentElement;void 0!==t.getBoundingClientRect&&(n=t.getBoundingClientRect());let a=t5(t);return{left:n.left+a.left-(o.clientLeft||0)+r.left,top:n.top+a.top-(o.clientTop||0)+r.top}}(this.lower.el)}dispose(){y().dispose(this.lower.el),delete this.lower}}let et={backgroundVpt:!0,backgroundColor:"",overlayVpt:!0,overlayColor:"",includeDefaultValues:!0,svgViewportTransformation:!0,renderOnAddRemove:!0,skipOffscreen:!0,enableRetinaScaling:!0,imageSmoothingEnabled:!0,controlsAboveOverlay:!1,allowTouchScrolling:!1,viewportTransform:[...M]};class ee extends tl(th){get lowerCanvasEl(){var t;return null===(t=this.elements.lower)||void 0===t?void 0:t.el}get contextContainer(){var t;return null===(t=this.elements.lower)||void 0===t?void 0:t.ctx}static getDefaults(){return ee.ownDefaults}constructor(t){let e=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{};super(),Object.assign(this,this.constructor.getDefaults()),this.set(e),this.initElements(t),this._setDimensionsImpl({width:this.width||this.elements.lower.el.width||0,height:this.height||this.elements.lower.el.height||0}),this.skipControlsDrawing=!1,this.viewportTransform=[...this.viewportTransform],this.calcViewportBoundaries()}initElements(t){this.elements=new t7(t)}add(){let t=super.add(...arguments);return arguments.length>0&&this.renderOnAddRemove&&this.requestRenderAll(),t}insertAt(t){for(var e=arguments.length,i=Array(e>1?e-1:0),r=1;r0&&this.renderOnAddRemove&&this.requestRenderAll(),s}remove(){let t=super.remove(...arguments);return t.length>0&&this.renderOnAddRemove&&this.requestRenderAll(),t}_onObjectAdded(t){t.canvas&&t.canvas!==this&&(g("warn","Canvas is trying to add an object that belongs to a different canvas.\nResulting to default behavior: removing object from previous canvas and adding to new canvas"),t.canvas.remove(t)),t._set("canvas",this),t.setCoords(),this.fire("object:added",{target:t}),t.fire("added",{target:this})}_onObjectRemoved(t){t._set("canvas",void 0),this.fire("object:removed",{target:t}),t.fire("removed",{target:this})}_onStackOrderChanged(){this.renderOnAddRemove&&this.requestRenderAll()}getRetinaScaling(){return this.enableRetinaScaling?b():1}calcOffset(){return this._offset=this.elements.calcOffset()}getWidth(){return this.width}getHeight(){return this.height}setWidth(t,e){return this.setDimensions({width:t},e)}setHeight(t,e){return this.setDimensions({height:t},e)}_setDimensionsImpl(t){let{cssOnly:e=!1,backstoreOnly:i=!1}=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{};if(!e){let e=l({width:this.width,height:this.height},t);this.elements.setDimensions(e,this.getRetinaScaling()),this.hasLostContext=!0,this.width=e.width,this.height=e.height}i||this.elements.setCSSDimensions(t),this.calcOffset()}setDimensions(t,e){this._setDimensionsImpl(t,e),e&&e.cssOnly||this.requestRenderAll()}getZoom(){return this.viewportTransform[0]}setViewportTransform(t){this.viewportTransform=t,this.calcViewportBoundaries(),this.renderOnAddRemove&&this.requestRenderAll()}zoomToPoint(t,e){let i=[...this.viewportTransform],r=tb(t,tS(i));i[0]=e,i[3]=e;let s=tb(r,i);i[4]+=t.x-s.x,i[5]+=t.y-s.y,this.setViewportTransform(i)}setZoom(t){this.zoomToPoint(new tn(0,0),t)}absolutePan(t){let e=[...this.viewportTransform];return e[4]=-t.x,e[5]=-t.y,this.setViewportTransform(e)}relativePan(t){return this.absolutePan(new tn(-t.x-this.viewportTransform[4],-t.y-this.viewportTransform[5]))}getElement(){return this.elements.lower.el}clearContext(t){t.clearRect(0,0,this.width,this.height)}getContext(){return this.elements.lower.ctx}clear(){this.remove(...this.getObjects()),this.backgroundImage=void 0,this.overlayImage=void 0,this.backgroundColor="",this.overlayColor="",this.clearContext(this.getContext()),this.fire("canvas:cleared"),this.renderOnAddRemove&&this.requestRenderAll()}renderAll(){this.cancelRequestedRender(),this.destroyed||this.renderCanvas(this.getContext(),this._objects)}renderAndReset(){this.nextRenderHandle=0,this.renderAll()}requestRenderAll(){this.nextRenderHandle||this.disposed||this.destroyed||(this.nextRenderHandle=tc(()=>this.renderAndReset()))}calcViewportBoundaries(){let t=this.width,e=this.height,i=tS(this.viewportTransform),r=tb({x:0,y:0},i),s=tb({x:t,y:e},i),n=r.min(s),o=r.max(s);return this.vptCoords={tl:n,tr:new tn(o.x,n.y),bl:new tn(n.x,o.y),br:o}}cancelRequestedRender(){this.nextRenderHandle&&(tu(this.nextRenderHandle),this.nextRenderHandle=0)}drawControls(t){}renderCanvas(t,e){if(this.destroyed)return;let i=this.viewportTransform,r=this.clipPath;this.calcViewportBoundaries(),this.clearContext(t),t.imageSmoothingEnabled=this.imageSmoothingEnabled,t.patternQuality="best",this.fire("before:render",{ctx:t}),this._renderBackground(t),t.save(),t.transform(i[0],i[1],i[2],i[3],i[4],i[5]),this._renderObjects(t,e),t.restore(),this.controlsAboveOverlay||this.skipControlsDrawing||this.drawControls(t),r&&(r._set("canvas",this),r.shouldCache(),r._transformDone=!0,r.renderCache({forClipping:!0}),this.drawClipPathOnCanvas(t,r)),this._renderOverlay(t),this.controlsAboveOverlay&&!this.skipControlsDrawing&&this.drawControls(t),this.fire("after:render",{ctx:t}),this.__cleanupTask&&(this.__cleanupTask(),this.__cleanupTask=void 0)}drawClipPathOnCanvas(t,e){let i=this.viewportTransform;t.save(),t.transform(...i),t.globalCompositeOperation="destination-in",e.transform(t),t.scale(1/e.zoomX,1/e.zoomY),t.drawImage(e._cacheCanvas,-e.cacheTranslationX,-e.cacheTranslationY),t.restore()}_renderObjects(t,e){for(let i=0,r=e.length;i!t.excludeFromExport).map(i=>this._toObject(i,t,e))},this.__serializeBgOverlay(t,e)),r?{clipPath:r}:null)}_toObject(t,e,i){let r;this.includeDefaultValues||(r=t.includeDefaultValues,t.includeDefaultValues=!1);let s=t[e](i);return this.includeDefaultValues||(t.includeDefaultValues=!!r),s}__serializeBgOverlay(t,e){let i={},r=this.backgroundImage,s=this.overlayImage,n=this.backgroundColor,o=this.overlayColor;return t$(n)?n.excludeFromExport||(i.background=n.toObject(e)):n&&(i.background=n),t$(o)?o.excludeFromExport||(i.overlay=o.toObject(e)):o&&(i.overlay=o),r&&!r.excludeFromExport&&(i.backgroundImage=this._toObject(r,t,e)),s&&!s.excludeFromExport&&(i.overlayImage=this._toObject(s,t,e)),i}toSVG(){let t=arguments.length>0&&void 0!==arguments[0]?arguments[0]:{},e=arguments.length>1?arguments[1]:void 0;t.reviver=e;let i=[];return this._setSVGPreamble(i,t),this._setSVGHeader(i,t),this.clipPath&&i.push('\n')),this._setSVGBgOverlayColor(i,"background"),this._setSVGBgOverlayImage(i,"backgroundImage",e),this._setSVGObjects(i,e),this.clipPath&&i.push("\n"),this._setSVGBgOverlayColor(i,"overlay"),this._setSVGBgOverlayImage(i,"overlayImage",e),i.push(""),i.join("")}_setSVGPreamble(t,e){e.suppressPreamble||t.push('\n','\n')}_setSVGHeader(t,e){let i;let r=e.width||"".concat(this.width),s=e.height||"".concat(this.height),n=d.NUM_FRACTION_DIGITS,o=e.viewBox;if(o)i='viewBox="'.concat(o.x," ").concat(o.y," ").concat(o.width," ").concat(o.height,'" ');else if(this.svgViewportTransformation){let t=this.viewportTransform;i='viewBox="'.concat(tq(-t[4]/t[0],n)," ").concat(tq(-t[5]/t[3],n)," ").concat(tq(this.width/t[0],n)," ").concat(tq(this.height/t[3],n),'" ')}else i='viewBox="0 0 '.concat(this.width," ").concat(this.height,'" ');t.push("