Skip to content

yannrapaport/mergepdf

Repository files navigation

MergePDF

A tool to merge odd and even pages from separate PDF files into a single document. This is particularly useful when scanning double-sided documents using a single-sided scanner.

MergePDF provides multiple ways to merge your PDF files:

  • Command-line interface with user-friendly progress indicators
  • REST API for programmatic access and integration
  • macOS Finder integration via Automator Quick Action

Features

  • Merge odd pages (1,3,5...) from one PDF with even pages (2,4,6...) from another
  • Handle reversed even pages from single-sided scanners
  • Visual progress indicators and native macOS notifications
  • Simple API for integration with other tools
  • Finder context menu integration

Installation

Quick Install (macOS)

  1. Download the latest release:

    curl -L https://github.com/yannrapaport/mergepdf/archive/refs/heads/main.zip -o mergepdf.zip
    unzip mergepdf.zip
    cd mergepdf-main
  2. Make the CLI script executable:

    chmod +x merge_pdfs_cli.sh
  3. Set up the background service:

    # Create the service configuration
    cp com.yannrapaport.mergepdf-api.plist ~/Library/LaunchAgents/
    
    # Edit paths in the configuration to match your installation
    # (replace USERNAME with your macOS username)
    sed -i '' "s|/Users/yannrapaport|/Users/$USER|g" ~/Library/LaunchAgents/com.yannrapaport.mergepdf-api.plist
    
    # Start the service
    launchctl load ~/Library/LaunchAgents/com.yannrapaport.mergepdf-api.plist
  4. Verify installation:

    curl http://localhost:8000/api/health

    You should see {"status":"ok"}

Command-Line Usage

The merge_pdfs_cli.sh script provides a user-friendly interface with progress indicators and descriptive feedback:

./merge_pdfs_cli.sh [OPTIONS] ODD_PDF EVEN_PDF

Options:

  • -o, --output FILE: Specify output filename (default: merged_TIMESTAMP.pdf)
  • -d, --dir DIR: Specify output directory (default: ~/Downloads)
  • -q, --quiet: Disable progress indicators
  • -h, --help: Display help message

Examples:

# Basic usage
./merge_pdfs_cli.sh odd_pages.pdf even_pages.pdf

# Specify output file and location
./merge_pdfs_cli.sh -o merged_document.pdf -d ~/Desktop odd_pages.pdf even_pages.pdf

API Usage

For programmatic access, MergePDF provides a REST API that can be accessed locally.

Starting the API manually (for testing):

python -m uvicorn api:app --host 127.0.0.1 --port 8000

API Endpoints:

  • POST /api/merge: Upload and merge two PDF files
  • GET /api/download/{job_id}: Download the merged PDF
  • GET /api/health: Check API health status

Example using curl:

# Upload files to merge
JOB_ID=$(curl -s -X POST "http://localhost:8000/api/merge" \
  -F "odd_file=@odd_pages.pdf" \
  -F "even_file=@even_pages.pdf" \
  -F "output_filename=merged.pdf" | grep -o '"job_id":"[^"]*' | cut -d'"' -f4)

# Download the merged file
curl -o merged.pdf "http://localhost:8000/api/download/$JOB_ID"

Service Management

The PDF merging service runs in the background and starts automatically when you log in.

Service Commands

# Check if service is running
curl http://localhost:8000/api/health

# Restart the service
launchctl unload ~/Library/LaunchAgents/com.yannrapaport.mergepdf-api.plist
launchctl load ~/Library/LaunchAgents/com.yannrapaport.mergepdf-api.plist

# Stop the service
launchctl unload ~/Library/LaunchAgents/com.yannrapaport.mergepdf-api.plist

# View service logs
cat /path/to/mergepdf/logs/api_*.log

macOS Finder Integration

MergePDF can be integrated into the macOS Finder context menu using Automator. This allows you to right-click on two PDF files and merge them directly.

For detailed setup instructions, see README_AUTOMATOR.md.

System Requirements

  • macOS 10.14 Mojave or newer
  • bash shell
  • curl (for API testing)

For Developers

If you want to modify or contribute to the project:

Development Setup

  1. Clone the repository:

    git clone https://github.com/yannrapaport/mergepdf.git
    cd mergepdf
  2. Create and activate a virtual environment:

    python3 -m venv venv
    source venv/bin/activate
  3. Install dependencies:

    pip install PyPDF2 fastapi uvicorn python-multipart

Technical Requirements

  • Python 3.6+
  • PyPDF2 (PDF manipulation)
  • FastAPI (API framework)
  • Uvicorn (ASGI server)
  • python-multipart (file upload handling)
  • bash (for CLI script)

License

This project is open source and available under the MIT License.

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published