RoadTripsGenerator/README.md

RoadTripsGenerator (RTG) est un logiciel qui génère un site web statique de road-trips : une carte interactive par voyage et par jour, avec les photos, les vidéos, les traces GPS et le récit du voyage.

C'est sans prétention et il faudrait probablement des développements bien plus sérieux pour obtenir un logiciel « presse-bouton », mais si cela peut donner des idées…

Je me suis rendu compte que je passais des heures à monter des films de mes road-trips que finalement je ne regardais pas moi-même : trop longs mais pas assez d'infos, pas interactifs, etc. Je me suis donc demandé sous quelle forme présenter mes voyages pour pouvoir me les remémorer en famille et les partager. C'est comme cela que ce petit projet a vu le jour.

Le principe

Pour chaque voyage, je dispose de photos et de vidéos géolocalisées (photos iPhone, films GoPro), des traces GPS de chaque journée et d'un récit écrit en Markdown.

RTG lit les positions GPS des photos et des vidéos, les placent sur une carte avec la trace du parcours découpée par jour, et construit des pages web où l'on peut, en parallèle, lire le récit du voyage. Voir par exemple mon road-trip de l'été 2025.

Il prépare aussi les médias pour le web :

• vidéos : un 720p H.264 lisible partout, chargé par défaut, et un 1080p HEVC proposé à la demande (environ 40 % plus léger que du H.264 à qualité égale) ;
• photos : une version allégée (1600 px, quelques centaines de Ko) affichée dans les diaporamas, le clic ouvrant l'original ;
• aperçus : une image tirée de chaque vidéo, affichée avant la lecture.

Les originaux ne sont jamais modifiés. Le site produit est statique : une simple copie suffit pour le publier ou le transporter.

Installation

RTG fonctionne sous macOS et Linux ; Windows devrait fonctionner mais n'a pas encore été testé. Il lui faut :

Élément	Rôle	Version
Python	le logiciel lui-même	3.10 ou plus récent
pipx	installe RTG et ses modules Python dans un espace à part	—
exiftool	lit les dates et positions GPS des photos et des vidéos	toute version récente
ffmpeg (avec libx265 et libx264)	compresse les vidéos, tire les images d'aperçu	5 ou plus récent

Les modules Python (folium, pandas, gpxpy, Pillow, pillow-heif…) sont installés automatiquement avec RTG.

macOS

1. Installer Homebrew s'il n'est pas déjà là :

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

2. Installer les outils, puis rendre pipx accessible :

   brew install python pipx exiftool ffmpeg
   pipx ensurepath
   

3. Ouvrir une nouvelle fenêtre de Terminal (ou taper source ~/.zshrc, zsh étant le shell par défaut de macOS) : pipx ensurepath ajoute ~/.local/bin au chemin des commandes, mais une fenêtre déjà ouverte ne le voit pas. Si rtg reste introuvable, c'est ce point.

Le ffmpeg de Homebrew contient libx265, libx264 et l'encodeur matériel VideoToolbox du Mac.

Linux (Debian, Ubuntu et dérivées)

sudo apt install python3 pipx ffmpeg libimage-exiftool-perl
pipx ensurepath

Puis fermer et rouvrir le terminal. Sur Fedora : sudo dnf install pipx perl-Image-ExifTool et ffmpeg depuis RPM Fusion.

Windows (non testé)

Dans PowerShell :

winget install Python.Python.3.12 Gyan.FFmpeg OliverBetz.ExifTool
py -m pip install --user pipx
py -m pipx ensurepath

Puis fermer et rouvrir PowerShell.

Installer RTG

Récupérer le dépôt (ou le copier, par exemple sur un disque externe) :

git clone https://git.ouaibe.fr/Korrigan/RoadTripsGenerator.git
pipx install --editable ./RoadTripsGenerator

Avec --editable, la commande rtg utilise directement le code du dossier : une mise à jour du dépôt (git pull) est prise en compte sans réinstaller. Le dossier doit alors rester accessible (disque branché).

Vérifier

rtg verifier

La commande contrôle Python, les modules, exiftool, ffmpeg et ses encodeurs, et donne pour chaque élément manquant la commande à taper sur votre système.

Premiers pas

cd /Volumes/CLEROADTRIPS/Road-Trips
rtg interface

L'interface s'ouvre dans le navigateur. Laisser la fenêtre de Terminal ouverte pendant l'utilisation ; Ctrl+C l'arrête.

• Site existant, organisé à l'ancienne (avant RTG) : rtg migrer écrit une fois site.toml et un voyage.toml par voyage.
• Nouveau site : lancer rtg interface dans un dossier vide ; l'interface propose de créer le site.

L'aide d'utilisation est dans l'interface : un bouton « ? » sur chaque écran et chaque onglet, et la page « Aide » du menu. Elle est aussi lisible ici, dans rtg/interface/aide/.

Organisation des dossiers

Le dépôt et le site sont deux dossiers voisins. Un voyage est un dossier qui contient un voyage.toml (ou, à l'ancienne, un des sous-dossiers photos, rushs ou routes). Les voyages rangés à la racine du site forment la rubrique « Voyages » de la page d'accueil ; ceux rangés un niveau plus bas, dans un dossier de regroupement (ici Balades), forment une rubrique du nom de ce dossier.

CLEROADTRIPS
|-RoadTripsGenerator          ce dépôt
| |-rtg                       le logiciel (interface, pages, encodage…)
| |-exemples                  docker-compose, nginx, admin.sh
| |-Scripts                   anciens scripts
|-Road-Trips                  le site
  |-site.toml                 réglages du site
  |-Ete-2025
  | |-voyage.toml             sources, infos et réglages du voyage
  | |-voyage.md               le récit
  | |-routes                  une trace GPX par jour (écrite par RTG)
  | |-photos, photos_web      photos et versions allégées
  | |-videos, apercus         vidéos encodées et images d'aperçu
  |-Balades
    |-Aisne-06-2026
      |-...

Les sources (rushs, photos, traces d'origine) peuvent rester sur d'autres disques ; leurs chemins sont notés dans voyage.toml.

Administration depuis le site : mise en place

Le bouton « Connexion » de l'accueil mène à l'interface, servie sous /admin/ par le serveur web du site. Exemple avec le site servi par un conteneur nginx derrière Traefik, et l'interface lancée directement sur le Mac :

Traefik (HTTPS) → nginx (le site, dans Docker) → /admin/ → RTG sur le Mac (host.docker.internal:8765)

L'interface ne tourne qu'à la demande (./admin.sh, ./admin.sh stop). Fermée, /admin/ affiche « Administration fermée » et le site reste en ligne. Sur le Mac, elle voit tous les disques et encode à pleine vitesse. Son utilisation est décrite dans l'aide de l'interface.

1. Mot de passe, une fois : rtg mot-de-passe (10 caractères au moins).
2. docker-compose.yml du site : le service nginx doit pouvoir joindre le Mac, avec extra_hosts: ["host.docker.internal:host-gateway"]. Voir exemples/docker-compose.yml.
3. nginx.conf : ajouter le bloc /admin/ et la page « Administration fermée », voir exemples/nginx-admin.conf. Le ^~ de location ^~ /admin/ est nécessaire si nginx.conf contient déjà une règle pour les .js, .css ou images.
4. docker compose up -d --remove-orphans.
5. admin.sh : copier exemples/admin.sh à côté du docker-compose.yml, puis chmod +x admin.sh et ./admin.sh. L'interface tourne en arrière-plan ; son journal est dans rtg-admin.log.
6. Dans l'interface, Réglages → Administration depuis le site : /admin/, puis « Refaire l'accueil » pour faire apparaître le bouton « Connexion ».

Après une mise à jour de RTG : ./admin.sh stop, puis ./admin.sh.

Variantes

• Interface dans un conteneur : exemples/docker-compose-conteneur.yml et exemples/admin-docker.sh, avec le Dockerfile à la racine du dépôt. L'encodage y est plus lent : il n'a que les processeurs que Docker Desktop attribue, et pas l'encodeur matériel du Mac. Chaque disque des sources doit aussi être déclaré dans Docker Desktop (Réglages → Resources → File sharing). Ne jamais déclarer /Volumes en entier : avec le partage de la clé du site, Docker Desktop échoue (« mkdir /host_mnt/Volumes/…: file exists ») et nginx ne démarre plus. Le mot de passe se copie à côté du compose : mkdir -p rtg-acces && cp ~/.config/rtg/acces.toml rtg-acces/.
• Traefik seul, sans nginx : exemples/traefik-rtg-admin.yml.
• Autre machine du réseau : rtg interface --distant (mot de passe obligatoire), de préférence en HTTPS (--certificat, --cle) ou par un tunnel SSH (ssh -L 8765:127.0.0.1:8765 serveur, puis l'adresse avec la clé affichée sur le serveur).

Le dossier du site étant publié tel quel, les .toml (chemins de vos disques) sont lisibles en ligne si le serveur web ne les refuse pas : la règle location ~ \.toml$ { deny all; } de l'exemple nginx s'en charge (Apache : <FilesMatch "\.toml$"> Require all denied </FilesMatch>).

Commandes

Tout ce que fait l'interface existe aussi dans le Terminal, depuis le dossier du site (Road-Trips) ou avec --racine CHEMIN.

Commande	Rôle
rtg interface	ouvrir l'interface dans le navigateur
rtg generer [VOYAGE…]	générer un, plusieurs ou tous les voyages, puis l'accueil
rtg etat	avancement de chaque voyage
rtg analyser VOYAGE	ce que RTG trouve dans les sources d'un voyage
rtg compresser VOYAGE	encoder les vidéos d'un voyage
rtg accueil	refaire l'accueil et la carte globale
rtg migrer	une fois : écrire site.toml et un voyage.toml par voyage d'après l'existant
rtg verifier	Python, exiftool et ffmpeg sont-ils bien installés ?
rtg mot-de-passe	définir le mot de passe de l'interface (--tester, --supprimer)

Options utiles

• rtg generer --sans-compression : sans encoder les vidéos.
• rtg generer --force : tout refaire, même ce qui est à jour.
• rtg generer --mymaps-maj : récupérer à nouveau les cartes Google My Maps.
• rtg compresser VOYAGE --reglages-changes : réencoder aussi les vidéos faites avec d'autres réglages que les actuels.
• rtg compresser VOYAGE --seulement 1080p (ou 720p) : ne traiter qu'une version.
• rtg compresser VOYAGE --force : tout réencoder.
• rtg interface --port 8765 --sans-navigateur : autre port, sans ouvrir le navigateur.
• rtg interface --proxy --prefixe /admin : derrière le serveur web du site (mot de passe obligatoire).
• rtg interface --arret-inactif 120 : s'arrêter après 120 minutes sans activité.
• rtg interface --distant [--certificat cert.pem --cle cle.pem] : accepter les connexions du réseau, mot de passe obligatoire, HTTPS conseillé.

Exemple : rtg compresser Balades/Aisne-06-2026 --reglages-changes --seulement 1080p.

Fichiers de réglages

Tout ce que fait l'interface est noté dans deux fichiers texte au format TOML. On peut aussi les modifier à la main ; une réécriture par l'interface garde les valeurs mais pas les commentaires.

site.toml (racine du site)

titre = "Nos Road-Trips"
adresse_publique = "https://roadtrips.ouaibe.fr/"
accueil_nb_recents = 2

[video]
qualite = "equilibree"      # econome | equilibree | haute
encodeur = "processeur"     # processeur | materiel
preset = "medium"
jobs = 0                    # 0 = automatique

[photos]
grand_cote = 1600
qualite = 80
positions_deduites = true

[journees]
fuseau = "Europe/Paris"
coupure_heure = 4

[carte_globale]
mymaps = ["https://www.google.com/maps/d/…"]

[administration]
adresse = "/admin/"         # bouton Connexion sur l'accueil

[confidentialite]
zones = [[48.80, 2.10, 500]]   # zones privées : latitude, longitude, rayon en m

voyage.toml (un par voyage)

titre = "Été 2026"
moto = "BMW R 1300 GS Adventure"

[sources]
traces = ["routes"]
videos = ["/Volumes/LaCie/Perso/Gopro/Gopro-2026/Ete-2026"]
photos = ["photos"]

[video]                     # réglages vidéo propres au voyage (facultatif)
qualite = "econome"
preset = "slow"
crf_hevc = 28
crf_h264 = 27

[dates_traces]              # jours imposés aux traces
"Etape 3.gpx" = "2026-08-03"

[positions]                 # médias placés à la main
"IMG_4831.jpeg" = [48.85, 2.35]

[corrections]
masques = [[48.85, 2.35, 300]]   # zones retirées des traces de ce voyage

Un chemin relatif (comme routes) part du dossier du voyage.

Publier

Le site est statique. Servi directement depuis son dossier (comme ici par nginx), il est en ligne dès la génération terminée. Sinon, il suffit de le copier : les sous-dossiers rushs (originaux, très lourds) et les fichiers export_*.csv sont inutiles en ligne ; photos reste nécessaire pour l'ouverture des originaux.

Anciens scripts

Les scripts de Scripts/ (genere_site.sh, compress.sh, prepare_web.py…) produisent le même site que RTG ; ils restent disponibles pendant la transition. Ils demandent d'installer à la main les modules Python : pip3 install pandas folium gpxpy markdown2 numpy pillow. bench_crf.sh mesure la qualité (VMAF ou SSIM) d'un extrait de rush à plusieurs CRF, pour choisir les réglages sur ses propres images.

La mise en page de RTG est dans rtg/templates/ (pages des voyages, accueil, carte globale) et rtg/interface/ (interface).

Contribuer

Pour pouvoir faire des push :

git remote set-url origin https://<nom d'utilisateur>@git.ouaibe.fr/Korrigan/RoadTripsGenerator.git

Pour éviter de retaper le mot de passe pendant une heure pour les autres push :

git config --global credential.helper 'cache --timeout=3600'