movmaker/README.md

# movmaker

Simple Python + ffmpeg movie maker.

Drop pictures, videos, music, and optionally one simple `data.txt` file into a single flat input directory. Then run one command to create an MP4 video.

No YAML. No required subdirectories.

## Requirements

- Python 3
- `ffmpeg`
- `ffprobe` usually included with ffmpeg

Install on Debian/Ubuntu/Raspberry Pi OS:

```bash
sudo apt install ffmpeg
```

## Fonts

The default title/stamp styling uses these fonts:

- Bebas Neue for the opening title, date, and location
- Noto Sans Bold for the bottom-left/bottom-right stamps
- IBM Plex Sans SemiBold for per-file captions

Both fonts support common Danish and Croatian characters such as `æ ø å Æ Ø Å č ć ž š đ Č Ć Ž Š Đ`.

Install them locally for the current user:

```bash
mkdir -p ~/.local/share/fonts/google
curl -L -o ~/.local/share/fonts/google/BebasNeue-Regular.ttf \
  'https://github.com/google/fonts/raw/main/ofl/bebasneue/BebasNeue-Regular.ttf'
sudo apt install fonts-noto-core fonts-ibm-plex
fc-cache -f
```

Check that fonts are available:

```bash
fc-match 'Bebas Neue'
fc-match 'Noto Sans'
fc-match 'IBM Plex Sans'
```

## Optional Jamendo music download

If the input folder has no audio file, movmaker can download one random track from Jamendo.

Save your Jamendo client ID in either an environment variable:

```bash
export JAMENDO_CLIENT_ID='your_client_id_here'
```

or in a local config file:

```bash
mkdir -p ~/.config/movmaker
echo 'JAMENDO_CLIENT_ID=your_client_id_here' > ~/.config/movmaker/jamendo.env
chmod 600 ~/.config/movmaker/jamendo.env
```

The default music search query is:

```text
cinematic punk rock
```

Override it with:

```bash
python3 movmaker.py input --music-genre "upbeat rock"
```

## Input folder

Example:

```text
input/
  IMG_001.jpg
  IMG_002.png
  holiday_clip.mp4
  music.mp3
  data.txt
```

Supported file types:

- Images: `.jpg`, `.jpeg`, `.png`, `.webp`, `.bmp`, `.tif`, `.tiff`
- Videos: `.mp4`, `.mov`, `.mkv`, `.avi`, `.webm`, `.m4v`
- Audio: `.mp3`, `.wav`, `.m4a`, `.aac`, `.flac`, `.ogg`
- Data: `data.txt`, `info.txt`, or `title.txt`

Files are ordered by filename, so names like this work well:

```text
001.jpg
002.jpg
003.mp4
004.jpg
```

## data.txt

`data.txt` is optional.

Simplest format:

```text
Paris Trip
Paris, France
May 2024
```

Those three lines mean:

1. title
2. location
3. date

If the date line is omitted, movmaker uses the date from the first picture/video and displays it like:

```text
May 2026
```

If the location line is omitted and GPS coordinates are found in the first picture/video that has them, movmaker reverse geocodes them and uses that as the location. It tries to return only `city/town/village, country`; if no city/town/village is found, it uses just the country.

Key/value format also works:

```text
title: Paris Trip
date: May 2024
place: Paris, France
```

Optional per-file captions are supported:

```text
IMG_001.jpg: Eiffel Tower
IMG_002.jpg: Louvre
IMG_003.jpg: First line | Second line
```

## Usage

Basic:

```bash
python3 movmaker.py input
```

With options:

```bash
python3 movmaker.py input \
  --out-dir . \
  --image-duration 6 \
  --fade 3 \
  --audio-fade 10 \
  --audio-fade-in 2 \
  --video-fade 1.5 \
  --music-genre "cinematic punk rock" \
  --resolution 1920x1080 \
  --fps 30
```

Fast preview render:

```bash
python3 movmaker.py input --preview
```

## Current behavior

- scans one flat input directory
- auto-detects media/audio/data files by extension
- shows each image fully visible for 6 seconds by default, not counting crossfades
- keeps the first image longer so the first transition starts after 2x image duration, 12 seconds by default
- includes video clips inline
- crossfades between media items over 3 seconds by default
- loops/trims music to match the video
- if no audio file exists in the input folder, searches Jamendo using `--music-genre` and downloads one random Creative Commons track that allows non-commercial reuse and derivative works; default query is `cinematic punk rock`
- reads the Jamendo client ID from `JAMENDO_CLIENT_ID` or `~/.config/movmaker/jamendo.env`
- fades music in over 2 seconds and out over 10 seconds by default
- fades video in/out over 1.5 seconds by default
- overlays the opening title for the first 6 seconds: large title, then date/location on one line
- displays optional per-file captions at bottom center with slightly off-white text and a soft shadow; use `|` to split caption lines
- adds persistent bottom-left title/date/place and bottom-right `Bubulescu.Org` stamps
- preserves special characters in rendered overlays and metadata
- uses safe ASCII only for generated filenames, so special letters become readable equivalents like `Č` -> `C`, `å` -> `a`, `ø` -> `o`
- embeds MP4 metadata: title, date, location/place, QuickTime location name, artist, comment, and creation_time
- writes an MP4 file named like `YYYYMMDD_title.mp4` in the current directory by default; use `--out-dir DIR` to choose another output directory
- takes `YYYYMMDD` from the first picture/video metadata, falling back to file modification date
- keeps console output minimal during rendering and writes detailed ffmpeg output to timestamped logs in `.logs/` inside the input directory
- uses local `ffmpeg/ffmpeg` and `ffmpeg/ffprobe` when present, otherwise system tools

## Notes

This is an early version. The intended workflow is deliberately simple: dump files into one folder and run the script.