{"id":31645238,"url":"https://github.com/welovemedia/ffmate","last_synced_at":"2026-01-14T11:53:54.680Z","repository":{"id":294173754,"uuid":"911152455","full_name":"welovemedia/ffmate","owner":"welovemedia","description":"FFmate is a modern and powerful automation layer built on top of FFmpeg - designed to make video and audio transcoding simpler, smarter, and easier to integrate","archived":false,"fork":false,"pushed_at":"2025-10-27T15:15:38.000Z","size":20489,"stargazers_count":536,"open_issues_count":0,"forks_count":29,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-27T17:19:16.710Z","etag":null,"topics":["automation","encoding","ffmpeg","go","golang","parser","presets","queue","rest","rest-api","restapi","watchfolder"],"latest_commit_sha":null,"homepage":"https://docs.ffmate.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/welovemedia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-02T11:08:12.000Z","updated_at":"2025-10-27T10:17:14.000Z","dependencies_parsed_at":"2025-06-24T13:21:31.151Z","dependency_job_id":"f8759c7a-0156-4d66-a516-07184fc544da","html_url":"https://github.com/welovemedia/ffmate","commit_stats":null,"previous_names":["welovemedia/ffmate"],"tags_count":94,"template":false,"template_full_name":null,"purl":"pkg:github/welovemedia/ffmate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/welovemedia%2Fffmate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/welovemedia%2Fffmate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/welovemedia%2Fffmate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/welovemedia%2Fffmate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/welovemedia","download_url":"https://codeload.github.com/welovemedia/ffmate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/welovemedia%2Fffmate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28419272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:47:48.104Z","status":"ssl_error","status_checked_at":"2026-01-14T10:46:19.031Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","encoding","ffmpeg","go","golang","parser","presets","queue","rest","rest-api","restapi","watchfolder"],"created_at":"2025-10-07T05:01:44.071Z","updated_at":"2026-01-14T11:53:54.675Z","avatar_url":"https://github.com/welovemedia.png","language":"Go","funding_links":[],"categories":["HarmonyOS","Go"],"sub_categories":["Windows Manager"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg style=\"text: center\" src=\"internal/service/tray/assets/icon.png\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/welovemedia/ffmate/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/welovemedia/ffmate?include_prereleases\" alt=\"Version\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/welovemedia/ffmate/actions\"\u003e\u003cimg src=\"https://github.com/welovemedia/ffmate/workflows/CI/badge.svg?brandh=dev\" alt=\"Build Status\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://coveralls.io/github/welovemedia/ffmate?branch=dev\"\u003e\u003cimg src=\"https://coveralls.io/repos/github/welovemedia/ffmate/badge.svg?branch=dev\" alt=\"Coverage Status\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/welovemedia/ffmate/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-AGPL--v3-green\" alt=\"License\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://pkg.go.dev/badge/github/welovemedia/ffmate/v2\"\u003e\u003cimg src=\"https://pkg.go.dev/badge/github/welovemedia/ffmate/v2.svg\" alt=\"Go Reference\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://goreportcard.com/report/github.com/welovemedia/ffmate/v2\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/welovemedia/ffmate/v2\" alt=\"Go Report\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://discord.gg/NzfeHn37jT\"\u003e\u003cimg src=\"https://img.shields.io/discord/1330908876912066650?logo=discord\" alt=\"Discord\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n## FFmate\n\nFFmate is an automation layer built on top of [FFmpeg](https://ffmpeg.org/), designed not only to simplify transcoding but also to serve as an **extensible engine for custom media workflows**. It provides developers with the tools to integrate FFmpeg's power into their applications and services through a comprehensive REST API, event-driven webhooks, and scriptable pre/post-processing hooks.\n\nIf you're looking to build custom media processing pipelines, integrate transcoding into your existing systems, or develop tools that leverage FFmpeg, FFmate provides the foundation.\n\n## ✨ Core Features for Extensibility\n\nFFmate is built with extensibility in mind. Here's how you can leverage its core components:\n\n- **REST API** – Submit and manage FFmpeg tasks programmatically\n- **Web UI** – Monitor and control jobs in real time, no terminal required\n- **Cluster Support** – Run multiple FFmate instances together, sharing the same database for scaling and redundancy\n- **Watchfolders** – Automatically process files dropped into a directory\n- **Presets** – Ready-made set of pre-configured transcoding presets for common use cases\n- **Webhooks** – Get real-time notifications for task events\n- **Dynamic Wildcards** – Automate file naming and folder structures\n- **Pre/Post Processing** – Run custom scripts before or after each task to automate complex workflow steps\n- **Built-in Queue** – Manage task execution with priority control and smart concurrency handling\n\n## 📚 Product Documentation\n\nWant to dive deeper into FFmate? The documentation covers everything—from API usage to Web UI features and real-world examples 👉 Everything you need is now available at [https://docs.ffmate.io](https://docs.ffmate.io)\n\n## 🚀 Getting Started for Developers\n\nTo start extending, integrating with, or contributing to FFmate:\n\n### Prerequisites\n\n*   **FFmpeg:** Installed and in `$PATH`.\n*   **Go (Golang):** Version 1.24+ (or specify your project's minimum version). Required for building from source or contributing to core.\n*   **Git:** For cloning the repository.\n*   Familiarity with REST APIs and JSON.\n*   Your preferred scripting language (Python, Bash, Node.js, etc.) for pre/post-processing scripts.\n\n### Installation \u0026 Setup\n\nYou have two main options:\n\n1.  **Use Pre-compiled Binaries (for integration/extension):**\n    *   Download the latest binary from [GitHub Releases](https://github.com/welovemedia/ffmate/releases).\n    *   Make executable: `chmod +x ffmate`\n    *   (Optional) Move to a directory in your `$PATH`.\n    *   Run FFmate Server: `./ffmate server`\n\n2.  **Build from Source (for core contribution/deep customization):**\n    *   **Clone the repository:**\n        ```bash\n        git clone https://github.com/welovemedia/ffmate.git\n        cd ffmate\n        ```\n    *   **Install Go dependencies:**\n        ```bash\n        go mod tidy\n        # or go get ./...\n        ```\n    *   **Build the FFmate binary:**\n        ```bash\n        go build -o ffmate main.go\n        ```\n        The compiled `ffmate` binary will be in the root of the `ffmate` directory.\n    *   **Run FFmate Server:**\n        ```bash\n        ./ffmate server\n        # For development, consider enabling debug for relevant namespaces:\n        # ./ffmate server --debug=\"api:webhook:queue:ffmpeg:sev\"\n        ```\n\nThe API will be available at `http://localhost:3000`.\n\n### Key Extension Points - Quick Reference\n\n*   **Integrating with an existing application?**\n    *   Start with the `/api/v1/tasks` endpoint to submit jobs.\n    *   Use `/api/v1/webhooks` to get status updates back to your application.\n*   **Need custom logic around transcoding?**\n    *   Implement pre/post-processing scripts.\n    *   Define `scriptPath` and `sidecarPath` in your task/preset API calls.\n*   **Building a custom dashboard or UI?**\n    *   The entire Web UI is built on the public REST API and WebSockets. You can do the same!\n    *   WebSockets (served from `/ws` on the same port) provide real-time updates for tasks and logs.\n*   **Automating complex ingestion workflows?**\n    *   Use the `/api/v1/watchfolders` endpoint combined with presets that trigger your custom processing logic.\n\n## 🔧 Understanding FFmate Internals \u0026 Code Structure\n\nFFmate is a Go application. A high-level overview of its structure and key components for extension:\n\n**Conceptual Diagram:**\n```mermaid\ngraph TD\n    %% ─── UI \u0026 API ─────────────────────────\n    YourApp[\"Your Application / Script\"] -- REST API --\u003e REST_API[\"FFmate REST API (Gin)\"]\n    WebUI[\"FFmate Web UI (Vue/React/Static)\"] -- REST API / WebSockets --\u003e REST_API\n\n    %% ─── Services (single row) ───────────\n    subgraph FFmate_Services [\"Services Layer (./internal/services)\"]\n        direction LR\n        TaskSvc[\"Task Service\"]\n        PresetSvc[\"Preset Service\"]\n        WatchfolderSvc[\"Watchfolder Service\"]\n        WebhookSvc[\"Webhook Service\"]\n    end\n    REST_API --\u003e TaskSvc\n    REST_API --\u003e PresetSvc\n    REST_API --\u003e WatchfolderSvc\n    REST_API --\u003e WebhookSvc\n\n    %% ─── Core \u0026 DB side-by-side ───────────\n    subgraph FFmate_Core [\"Core Logic (./internal/core, ./internal/ffmpeg)\"]\n        direction LR\n        Queue[\"Task Queue Processor\"]\n        PrePostScripts[\"Pre/Post-Processing Engine\"]\n        DB[(SQLite DB - GORM)]\n    end\n    TaskSvc --\u003e Queue\n    Queue --\u003e PrePostScripts\n    PrePostScripts --\u003e FFMpegBinary[\"ffmpeg Binary Wrapper\"]\n    Queue --\u003e DB\n    WebhookSvc -- Event Bus/Direct Call --\u003e YourAppWebhook[\"Your Webhook Endpoint\"]\n\n    FFMpegBinary -- system call --\u003e ActualFFmpeg[\"ffmpeg (External Binary)\"]\n\n\n    %% ─── Styling ───────────\n    style YourApp fill:#e6ffe6,stroke:#009933,stroke-width:1.5px,color:#000;\n    style YourAppWebhook fill:#e6ffe6,stroke:#009933,stroke-width:1.5px,color:#000;\n    classDef ui     fill:#99d6ff,stroke:#2060a0,stroke-width:1.2px,color:#000000;\n    classDef api    fill:#b3e0ff,stroke:#2060a0,stroke-width:1.2px,color:#000000;\n    classDef svc    fill:#bdb4ff,stroke:#4b44a0,stroke-width:1.2px,color:#000000;\n    classDef core   fill:#99ff99,stroke:#2d7a2d,stroke-width:1.2px,color:#000000;\n    classDef db     fill:#ffcc80,stroke:#b36b00,stroke-width:1.2px,color:#000000;\n    classDef ffbin  fill:#ff99cc,stroke:#b3366b,stroke-width:1.2px,color:#000000;\n```\n\n**Code Structure:**\n\n*   **`main.go`**: Main application entry point, CLI command parsing (using Cobra), server initialization.\n*   **`/internal/`**: Core application logic, not intended for direct import by other projects.\n    *   **`/controller/`**: HTTP request handlers (e.g., using Gin). This is where API routes are defined and map to services.\n    *   **`/services/`**: Business logic for each major feature (Tasks, Presets, Watchfolders, Webhooks). Services orchestrate operations, interact with the database, and call core components.\n    *   **`/dto/`**: A folder holding all Data Transfer Objects.\n    *   **`/queue/`**: Manages the task queue, concurrency, and task lifecycle.\n    *   **`/interceptor/`**: Interceptors to use with Gin for various routes.\n    *   **`/middleware/`**: Global middleware being used by Gin.\n    *   **`/metrics/`**: Manages and exposes prometheus metrics for later scraping.\n    *   **`/ffmpeg/`**: Wrapper around the `ffmpeg` binary, responsible for executing commands, parsing progress, and handling output/errors.\n    *   **`/database/`**: Database models/structs (e.g., for GORM if used) and database interaction logic (repository pattern).\n    *   **`/config/`**: Application configuration management.\n    *   **`/utils/`**: Common utility functions.\n*   **`/pkg/`**: Libraries intended to be used by external applications (if any). (Your current docs don't suggest FFmate is used as a library itself, mostly as a standalone server).\n*   **`/ui/`** or **`/web/dist/`**: Contains the pre-built static assets for the Web UI.\n*   **`/docs/`**: Your Markdown documentation.\n*   **`go.mod`, `go.sum`**: Go module files.\n\n**Key Extension \u0026 Contribution Areas:**\n\n*   **API Handlers (`/internal/controller/`):** Extend existing API endpoints or add new ones.\n*   **Services (`/internal/services/`):** Modify or add business logic for features.\n*   **Core Logic (`/internal/ffmpeg/`):** Enhance task processing, FFmpeg interaction, or pre/post-script handling.\n*   **Web UI (`/ui/`):** The ffmate-ui repository as submodule.\n\n## 🤝 Contributing to FFmate Core\n\nInterested in contributing directly to FFmate's development? We welcome contributions!\n\n1.  **Understand the Project:** Familiarize yourself with the existing documentation and code structure (see \"Understanding FFmate Internals \u0026 Code Structure\" above).\n2.  **Setup your Environment:** Ensure you have Go (see prerequisites) and Git installed.\n3.  **Find an Issue or Propose an Enhancement:** Check existing [GitHub Issues](https://github.com/welovemedia/ffmate/issues) or discuss your ideas on Discord first.\n4.  **Fork the Project.**\n5.  **Clone your fork and build from source** (see \"Build from Source\" instructions above).\n6.  **Create your Feature Branch:** (`git checkout -b feature/YourAmazingFeature`).\n7.  **Write Code \u0026 Tests:** Implement your feature or fix. Add unit tests where appropriate.\n8.  **Ensure Code Quality:**\n    *   Run `go fmt ./...` to format your code.\n    *   Run `go vet ./...` to check for suspicious constructs.\n    *   (If linters like `golangci-lint` are used, run them).\n9.  **Commit your Changes:** (`git commit -m 'feat: Add YourAmazingFeature'`). Follow conventional commit messages if applicable.\n10. **Push to the Branch:** (`git push origin feature/YourAmazingFeature`).\n11. **Open a Pull Request** against the `main` (or `develop`) branch of the original `welovemedia/ffmate` repository. Provide a clear description of your changes.\n\n## 💬 Developer Community \u0026 Support\n\n*   **Discord (Developer Chat):** Join our [FFmate Community on Discord](https://discord.gg/NzfeHn37jT) for discussions on extending FFmate, asking technical questions, and sharing your projects.\n*   **GitHub Issues:** Report bugs, discuss potential enhancements [GitHub Issues](https://github.com/welovemedia/ffmate/issues).\n\n## 📄 License\n\nThis project is licensed under the **AGPL-3.0**. See the [LICENSE](LICENSE) file for full details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwelovemedia%2Fffmate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwelovemedia%2Fffmate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwelovemedia%2Fffmate/lists"}