# mp3-to-mp4

## Purpose

Convert an MP3 audio file into an MP4 video that displays a static title card, suitable for uploading to video platforms.

## Dependencies

- `ffmpeg` (6.x+) — video/audio encoding

## Usage

```
mp3-to-mp4 [OPTIONS] <input.mp3>
```

### Arguments

| Argument | Description |
|---|---|
| `<input.mp3>` | Path to the MP3 file to convert (required) |

### Options

| Flag | Description |
|---|---|
| `--title`, `-t` | Title text to display on the video (required) |
| `--output`, `-o` | Output file path (default: same name as input with `.mp4` extension) |
| `--resolution`, `-r` | Video resolution as WxH (default: `1920x1080`) |
| `--font-size` | Font size in pixels (default: `72`) |
| `--font-color` | Font colour (default: `white`) |
| `--bg-color` | Background colour (default: `black`; ignored when `--image` is set) |
| `--image`, `-i` | Background image path (optional; scaled to fill the resolution) |
| `--dryrun`, `-n` | Preview what would happen without creating files |
| `--help`, `-h` | Show usage information |

## Behaviour

1. **Validate inputs.** Check that `<input.mp3>` exists and is readable. Check that `ffmpeg` is on PATH. Check that `--title` is provided. Exit 1 with a clear message if any check fails.

2. **Determine duration.** Use `ffprobe` to get the audio duration in seconds.

3. **Generate video.** Use ffmpeg to:
   - **Without `--image`:** Create a solid colour background at the specified resolution for the audio duration. Title is centred both horizontally and vertically.
   - **With `--image`:** Scale the image to fill the resolution (crop to fit). Title is centred horizontally near the bottom of the frame.
   - Mux the MP3 audio as the audio stream
   - Encode with H.264 video and AAC audio for broad compatibility
   - Use `-shortest` to match video duration to audio duration

4. **Report.** Print the output path on success.

## Dryrun Behaviour

When `--dryrun` / `-n` is passed:

```
[dryrun] Input:       /path/to/episode.mp3
[dryrun] Output:      /path/to/episode.mp4
[dryrun] Title:       My Podcast Episode
[dryrun] Duration:    3m 42s
[dryrun] Resolution:  1920x1080
[dryrun] Font size:   72
[dryrun] Font color:  white
[dryrun] Background:  black (or image path when --image is used)
[dryrun] Dependencies OK: ffmpeg 6.1.1
[dryrun] Would generate .mp4 video file
```

No files are created or modified.

## Edge Cases

- **Input file not found:** Exit 1 with `Error: file not found: <path>`
- **ffmpeg not installed:** Exit 1 with `Error: ffmpeg not found. Install with: sudo apt install ffmpeg`
- **--title not provided:** Exit 1 with `Error: --title is required`
- **Output file already exists:** Overwrite without prompting (standard pipeline behaviour)
- **Title text is very long:** ffmpeg's drawtext wraps naturally; no special handling needed
- **Input is not a valid audio file:** ffprobe will fail; exit 1 with `Error: could not read audio duration from: <path>`
- **--image file not found:** Exit 1 with `Error: image not found: <path>`
- **--image with --bg-color:** `--bg-color` is silently ignored when `--image` is provided

## Examples

```bash
# Basic conversion
mp3-to-mp4 -t "My Podcast Episode" episode.mp3

# Custom output and resolution
mp3-to-mp4 -t "Talk Title" -o talk.mp4 -r 1280x720 recording.mp3

# Custom styling
mp3-to-mp4 -t "Keynote" --font-size 96 --font-color yellow --bg-color "#1a1a2e" speech.mp3

# With a background image (title at bottom)
mp3-to-mp4 -t "Keynote 2026" -i cover.jpg recording.mp3

# Preview without creating files
mp3-to-mp4 --dryrun -t "Test" audio.mp3
```