Developer Guide

Developer Guide

Information for developers who want to contribute to or extend EncodeForge.

Table of Contents

• Architecture
• Development Setup
• Project Structure
• Contributing
• Code Standards
• Testing
• Pull Requests

Architecture

Overview

EncodeForge consists of three main components:

1. Java GUI - JavaFX-based desktop application
2. Python Core - FFmpeg operations and processing
3. Bridge - Communication between Java and Python

Component Diagram

┌─────────────────────────────────────────┐
│         JavaFX GUI (Frontend)           │
│  - MainController                       │
│  - UI Components                        │
│  - Event Handling                      │
└──────────────┬──────────────────────────┘
               │
               │ PythonBridge
               │
┌──────────────▼──────────────────────────┐
│      Python Core (Backend)              │
│  - EncodeForgeCore                      │
│  - ConversionHandler                    │
│  - SubtitleHandler                      │
│  - RenamingHandler                      │
│  - FFmpegManager                        │
└──────────────┬──────────────────────────┘
               │
               │ FFmpeg / Providers
               │
┌──────────────▼──────────────────────────┐
│   External Services                     │
│  - FFmpeg                               │
│  - Whisper AI                           │
│  - TMDB/TVDB APIs                       │
│  - Subtitle Providers                   │
└─────────────────────────────────────────┘

Technology Stack

Frontend:

• Java 17
• JavaFX 17
• Maven
• FXML for UI

Backend:

• Python 3.8+
• FFmpeg
• OpenAI Whisper
• Requests (API calls)

Build:

• Maven (Java)
• jpackage (Native installers)
• Python (CLI/Web UI)

Development Setup

Prerequisites

1. Java 17+

   java -version

2. Maven 3.8+

   mvn -version

3. Python 3.8+

   python --version

4. FFmpeg

   ffmpeg -version

5. Git

   git --version

Clone Repository

git clone https://github.com/yourusername/encodeforge.git
cd encodeforge

Setup Java Project

cd EncodeForge
mvn clean install

Setup Python Project

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Run Development Version

Java GUI:

cd EncodeForge
mvn javafx:run

CLI:

cd EncodeForge/src/main/resources/python
python encodeforge_cli.py --help

Web UI:

cd EncodeForge/src/main/resources/python
streamlit run encodeforge_webui.py

Project Structure

Java Structure

EncodeForge/src/main/java/com/encodeforge/
├── MainApp.java                    # Application entry point
├── controller/                     # MVC Controllers
│   ├── MainController.java
│   ├── InitializationDialog.java
│   └── ...
├── service/                        # Business logic
│   ├── DependencyManager.java
│   ├── PythonBridge.java
│   └── ...
├── util/                           # Utilities
│   ├── PathManager.java
│   ├── ResourceExtractor.java
│   └── ...
└── model/                          # Data models
    └── ...

Python Structure

EncodeForge/src/main/resources/python/
├── encodeforge_core.py             # Main orchestrator
├── encodeforge_cli.py              # CLI interface
├── encodeforge_webui.py            # Web UI
├── encodeforge_api.py              # API wrapper
├── ffmpeg_core.py                  # FFmpeg operations
├── ffmpeg_manager.py                # FFmpeg management
├── subtitle_manager.py             # Subtitle operations
├── metadata_grabber.py             # Metadata fetching
├── profile_manager.py              # Profile management
├── encodeforge_modules/            # Core modules
│   ├── conversion_handler.py
│   ├── subtitle_handler.py
│   ├── renaming_handler.py
│   └── ...
├── subtitle_providers/              # Subtitle providers
│   ├── whisper_manager.py
│   ├── opensubtitles_manager.py
│   └── ...
└── metadata_providers/              # Metadata providers
    ├── tmdb_provider.py
    ├── tvdb_provider.py
    └── ...

Contributing

Getting Started

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Contribution Areas

Code:

• Bug fixes
• New features
• Performance improvements
• Code refactoring

Documentation:

• Wiki pages
• Code comments
• README updates
• Tutorials

Testing:

• Unit tests
• Integration tests
• Bug reports
• Test cases

Design:

• UI/UX improvements
• Icons and graphics
• Themes
• Layout improvements

Code Standards

Java

Style:

• Follow Java conventions
• Use meaningful names
• Add JavaDoc comments
• Keep methods small
• Avoid deep nesting

Example:

/**
 * Processes video files using hardware acceleration.
 * 
 * @param files List of video files to process
 * @param settings Conversion settings
 * @return Processing results
 */
public ProcessingResult processFiles(List<File> files, ConversionSettings settings) {
    // Implementation
}

Python

Style:

• Follow PEP 8
• Use type hints
• Add docstrings
• Max line length: 100 characters
• Use meaningful names

Example:

def process_video(
    file_path: str,
    settings: ConversionSettings
) -> ProcessingResult:
    """
    Process video file with given settings.
    
    Args:
        file_path: Path to video file
        settings: Conversion settings
        
    Returns:
        Processing result with status and output
    """
    # Implementation

Git Commit Messages

Format:

<type>: <subject>

<body>

<footer>

Types:

• feat - New feature
• fix - Bug fix
• docs - Documentation
• style - Formatting
• refactor - Code refactoring
• test - Tests
• chore - Maintenance

Example:

feat: Add support for AMD AMF hardware acceleration

- Implement AMD AMF encoder detection
- Add AMF-specific settings
- Update UI to show AMF options

Closes #123

Testing

Unit Tests

Java:

mvn test

Python:

pytest tests/

Integration Tests

Test full workflows:

• Encoding pipeline
• Subtitle generation
• Metadata fetching
• File renaming

Manual Testing

Test Checklist:

• All three modes work
• Hardware acceleration detected
• Subtitles generate/download
• Metadata fetches correctly
• Settings save/load
• Logs display properly
• Error handling works

Pull Requests

Before Submitting

1. Test your changes thoroughly
2. Update documentation if needed
3. Follow code standards
4. Add tests for new features
5. Rebase on latest main branch

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
How did you test your changes?

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] No new warnings

Review Process

1. Maintainer reviews code
2. Automated tests run
3. Changes requested if needed
4. Approval and merge

Advanced Topics

Adding a New Provider

Subtitle Provider:

1. Create provider class in subtitle_providers/
2. Inherit from BaseProvider
3. Implement required methods
4. Register in subtitle_manager.py

Metadata Provider:

1. Create provider class in metadata_providers/
2. Inherit from BaseProvider
3. Implement API calls
4. Register in metadata_grabber.py

Adding a New Feature

1. Plan the feature
2. Design the architecture
3. Implement backend logic
4. Add UI components
5. Test thoroughly
6. Document usage

Performance Optimization

Profiling:

• Use Java Flight Recorder for Java
• Use cProfile for Python
• Identify bottlenecks
• Optimize critical paths

Techniques:

• Parallel processing
• Caching
• Lazy loading
• Memory optimization

Resources

Documentation

• JavaFX Documentation
• FFmpeg Documentation
• Whisper Documentation
• Streamlit Documentation

Community

• GitHub Issues
• GitHub Discussions
• Discord (if available)

License

Contributions are licensed under MIT License.

---

Ready to contribute? Start by forking the repository and creating a feature branch!