FFmpeg GUI

A modern desktop application for generic command execution with dynamic configuration, built with Electron and Vue.js 3.

Overview

FFmpeg GUI has evolved from a simple FFmpeg video converter to a generic command execution framework that supports any command-line tool through dynamic JSON configuration. The application provides a user-friendly interface for selecting files, configuring command options, and executing batch operations with concurrency control.

Key Features

• 🏗️ Generic Command Framework: Support for any command-line tool via JSON configuration
• 📁 File System Explorer: Browse and select files/directories with multi-selection support
• ⚙️ Dynamic Command Configuration: Load commands and options from JSON configuration
• 🔄 Batch Processing: Process multiple files with configurable concurrency (1-4 parallel jobs)
• 🛡️ Duplicate Detection: Automatic detection and handling of duplicate files
• 📊 Status Tracking: Real-time status updates for all processing jobs
• 🔧 Cross-Platform: Works on Windows and Unix systems

Quick Start

Prerequisites

• Node.js (v18 or higher)
• npm or yarn
• Command-line tools you want to use (e.g., FFmpeg for video conversion)

Installation

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production (renderer process only)
npm run build

# Build Electron app (unpacked, no installer)
npm run build:electron

# Package the application (creates installers)
npm run dist

Usage

1. Browse Files: Use the file explorer to navigate and select files/directories
2. Select Command: Choose a command from the dropdown (loaded from configuration)
3. Configure Options: Click "Configure Options" to set command parameters
4. Set Output Directory: Select where processed files should be saved
5. Start Processing: Click "Start Processing" to begin batch execution

Architecture

The application follows Electron's multi-process architecture:

• Main Process (electron/main.ts): Handles file system operations and command execution
• Renderer Process (src/): Vue.js 3 application with TypeScript and Composition API
• Preload Script (electron/preload.ts): Secure API bridge between processes
• State Management: Pinia stores for centralized state management
• Dynamic Configuration: JSON-based command definitions in public/command-options.json

Key Components

• FileExplorer.vue: File browser with navigation and multi-selection
• ProcessQueue.vue: Processing queue display with status tracking
• ConversionSettings.vue: Command selection and output configuration
• CommandOptionsModal.vue: Command options editor with categorized tabs

Configuration

Commands are defined in public/command-options.json using a flexible schema:

{
  "commands": {
    "cp": {
      "name": "Copy Files",
      "description": "Copy files to destination directory",
      "categories": [
        {
          "name": "Basic",
          "options": [
            {
              "name": "preserve",
              "type": "boolean",
              "description": "Preserve file attributes",
              "default": true
            }
          ]
        }
      ]
    }
  }
}

Development

Project Structure

ffmpeg-gui/
├── electron/          # Electron main process
├── src/              # Vue.js 3 application
│   ├── components/   # Vue components
│   ├── services/     # Business logic
│   ├── stores/       # Pinia stores
│   └── types/        # TypeScript definitions
├── public/           # Static assets and configuration
└── docs/             # Documentation

Development Commands

# Development with hot reload
npm run dev

# Build web assets (production)
npm run build

# Build Electron app (unpacked)
npm run build:electron

# Package application for distribution
npm run dist

# Run built Electron app
npm run electron

# Clean build outputs
npm run clean

Documentation

For comprehensive technical documentation, see:

• docs/architecture.md - Detailed technical architecture and design
• docs/AGENTS.md - Project documentation hub and AI agent guidelines

Contributing

1. Follow TypeScript strict mode guidelines
2. Use Vue 3 Composition API with <script setup> syntax
3. Maintain type safety throughout
4. Add new commands via JSON configuration
5. Test cross-platform compatibility

License

This project is under active development.