Installer Jarvis · Réveiller son bureau en claquant des mains (macOS) · Guide complet

🎁 Ce que tu reçois : le prompt complet à coller dans Claude Code (il fait tout le travail technique à ta place), les 5 adaptations macOS d'un projet écrit pour Windows, et la méthode de détection qui distingue vraiment un clap d'une voix. 15 minutes, zéro ligne de code à écrire toi-même.

🎯 Le résultat : tu claques deux fois des mains, et ton bureau se réveille tout seul. Ton navigateur s'ouvre sur ton dashboard, tes apps se placent sur les bons écrans, ta musique démarre et une voix te fait ton brief du matin par-dessus.

Ce que ça fait exactement

1. Un script Python écoute ton micro en continu (très léger, aucun envoi sur Internet).
2. Il détecte un double clap, et uniquement un double clap : ni ta voix, ni la musique.
3. Il ouvre tes apps et les place aux bons endroits sur tes écrans.
4. Il lance ton morceau Spotify.
5. Une voix ElevenLabs te dit ta phrase par-dessus la musique.

Ce qu'il te faut

• Un Mac (le projet d'origine est écrit pour Windows, on l'adapte).
• Python 3 installé : tape python3 --version dans le Terminal pour vérifier.
• Spotify installé en application de bureau (l'app, pas le site web).
• Un compte ElevenLabs gratuit pour la voix (optionnel : tout le reste marche sans).
• Claude Code, qui va faire le travail à ta place.

1. Le prompt à copier-coller dans Claude Code

C'est le cœur du guide. Ouvre Claude Code dans un dossier vide, colle ce prompt tel quel, et laisse-toi guider : Claude te posera les questions une par une et fera tout le travail technique.

Installe-moi le projet Jarvis (double clap → réveil du bureau) depuis ce repo :
https://github.com/hectorg2211/jarvis

TON RÔLE : tu fais TOUT le travail technique. Je ne veux écrire aucune ligne de
code. Pose-moi des questions une par une, en langage simple, et configure au fur
et à mesure. Ne me montre pas le code sauf si je le demande.

IMPORTANT — n'utilise aucun réglage par défaut du repo. Il est configuré pour son
auteur : il ouvre Binance, Chrome, Cursor et son propre morceau Spotify. Remplace
TOUT par mes réponses, et supprime ce que je ne demande pas.

ÉTAPE 1 — Demande-moi d'abord, une question à la fois :
1. Quel système j'utilise (macOS ou Windows)
2. Quelle musique je veux au réveil (je te donnerai un lien Spotify)
3. Qu'est-ce que je veux voir s'ouvrir quand je claque des mains ? Ne te contente
   pas de poser la question : propose-moi une liste d'options concrètes et laisse-moi
   choisir ou compléter. Par exemple : Claude, Gmail, mon agenda, Notion, mon CRM,
   un dashboard perso, Slack, mon éditeur de code, YouTube Studio, une page web
   précise. Demande-moi l'URL exacte pour chaque site.
4. Si j'ai plusieurs écrans, et quelle app va sur quel écran
5. Ce que la voix doit me dire exactement

ÉTAPE 2 — Installe le projet. Sur macOS, le Python de Homebrew est "externally
managed" : pip install échoue avec l'erreur PEP 668, et la commande python
n'existe pas (c'est python3). Crée donc un environnement virtuel dans le dossier
du projet et installe dedans :
    python3 -m venv .venv
    .venv/bin/python -m pip install -r requirements.txt
Utilise ensuite toujours .venv/bin/python pour lancer. N'utilise jamais
--break-system-packages. Ajoute .venv/, .env et .cache/ au .gitignore.

ÉTAPE 3 — Adapte le code à macOS si besoin. Le projet est écrit pour Windows.
Voici les points précis, ils viennent d'une adaptation déjà faite et testée :
- Ouvrir les apps : remplace os.startfile() et les chemins .exe par
  subprocess.Popen(["open", "-a", "NomDeLApp"]). Attention : le nom de l'app et le
  nom de son processus peuvent différer (Opera GX se lance ainsi mais son process
  s'appelle Opera).
- Placer les fenêtres : l'API Win32 n'existe pas. Utilise AppleScript via osascript
  (tell application "System Events" to set position/size of window 1). Détecte les
  écrans avec NSScreen.screens() pour que ça marche écran externe branché ou non.
  Un 2e écran au-dessus a des Y négatifs, à gauche des X négatifs.
- Musique : pilote Spotify en AppleScript (tell application "Spotify" to play track
  "spotify:track:ID"). Convertis un lien https://open.spotify.com/track/ID en URI
  spotify:track:ID. Envoie un pause juste avant le play track, sinon Spotify joue
  d'abord 2-3 s du morceau précédent. Et réapplique le volume après le chargement,
  Spotify le remet à 100 tout seul.
- Jouer la voix : dans le SDK ElevenLabs v2+, "from elevenlabs import play" importe
  un MODULE, pas une fonction (erreur 'module' object is not callable), et le lecteur
  intégré exige ffmpeg. Écris plutôt le MP3 sur disque et joue-le avec afplay.
  Mets-le en cache (nom = hash de la phrase) pour que la voix parte instantanément
  aux lancements suivants.
- Micro : les MacBook échantillonnent à 48000 Hz, pas 44100. Un mauvais SAMPLE_RATE
  est la cause n°1 des claps non détectés.

ÉTAPE 4 — La détection du clap, le vrai piège. Détecter par le volume seul ne
marche pas : une voix humaine atteint le même niveau qu'un clap (mesuré : clap
0.42-0.66, voix 0.54). Le script se déclenche alors tout seul dès que quelqu'un
parle ou que la musique tourne.
Filtre par la FORME du son : un clap s'effondre en moins de 100 ms, une voix reste
forte. Concrètement — quand un pic dépasse le seuil, ne déclenche pas tout de suite :
attends 100 ms et vérifie que le niveau est retombé sous 35 % du pic. Si oui c'est
un clap, sinon c'est de la voix ou de la musique.
Prévois un plancher absolu (MIN_RMS ≈ 0.28) et un écart entre les deux claps de
0.10 s à 0.75 s.

ÉTAPE 5 — La voix. Guide-moi pour créer ma clé ElevenLabs et choisir un Voice ID,
puis crée le .env. Préviens-moi que sur le plan gratuit, les voix de la Voice
Library sont refusées par l'API (erreur 402) : seules les voix natives fonctionnent.

ÉTAPE 6 — Ajoute un mode debug activable par variable d'environnement, qui affiche
le niveau mesuré et le seuil à chaque pic. Puis explique-moi comment lancer, et
reste avec moi pendant que je teste mon premier clap.

ÉTAPE 7 — Le système de SCÈNES. Je ne veux pas une seule action : je veux que
chaque double clap déclenche une scène différente, et que ça reboucle sur la
première à la fin. Une scène = un nom + une phrase + un morceau Spotify + le fait
d'ouvrir les apps ou non.
Exemple concret de ce que je veux :
  - clap 1 → scène "réveil" : ouvre mes apps, lance ma musique du matin, la voix me
    fait mon brief de la journée
  - clap 2 → scène "outro" : n'ouvre AUCUNE app (elles sont déjà ouvertes), lance
    un autre morceau, la voix dit mon texte de fin de vidéo
  - clap 3 → on repart sur la scène "réveil"
Mets les scènes dans un fichier de config lisible (un config.json à la racine), pas
en dur dans le code, pour que je puisse en ajouter d'autres sans y toucher.
Pré-génère les voix de TOUTES les scènes au démarrage du script : comme ça chaque
scène part instantanément, sans attendre l'API.
Affiche la liste des scènes au lancement pour que je voie ce qui est chargé.
Demande-moi la phrase exacte et le lien Spotify de chaque scène, une scène à la fois.

2. Récupérer le projet

Ouvre ton Terminal, crée un dossier pour le projet, puis clone le dépôt :

mkdir -p ~/Documents/JARVIS && cd ~/Documents/JARVIS
git clone https://github.com/hectorg2211/jarvis .

⚠️ Ne lance surtout pas le projet tel quel. Il est configuré pour son auteur : il ouvre Binance, Cursor et son propre morceau Spotify. Tout doit être remplacé par tes réglages à toi.

3. L'environnement Python (le piège numéro 1 sur Mac)

Sur macOS, le Python installé par Homebrew est protégé : un pip install classique échoue avec une erreur PEP 668 / externally managed environment. Et la commande python n'existe pas, c'est python3.

La solution est un environnement virtuel, un dossier isolé où les librairies s'installent sans toucher au système :

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Ensuite, on lance toujours avec .venv/bin/python, jamais avec python3 tout seul.

🚫 Si tu vois un conseil qui dit d'utiliser --break-system-packages : ne le fais pas. Comme son nom l'indique, ça casse le Python de ton système.

4. Les 5 adaptations macOS obligatoires

Le projet est écrit pour Windows. Voici les cinq points qui doivent être réécrits, à donner tels quels à Claude Code.

1. Ouvrir les applications

Windows utilise os.startfile() et des chemins vers des fichiers .exe. Rien de tout ça n'existe sur Mac. Il faut :

subprocess.Popen(["open", "-a", "NomDeLApp"])

💡 Piège vicieux : le nom de l'app pour la lancer et le nom de son processus interne peuvent être différents. Exemple réel : Opera GX se lance avec open -a "Opera GX" mais son processus s'appelle juste Opera. Si tu te trompes, le placement des fenêtres échoue en silence, sans message d'erreur.

2. Placer les fenêtres sur les écrans

L'API Win32 n'existe pas sur Mac. On passe par AppleScript :

tell application "System Events"
	tell process "Notion"
		set position of window 1 to {0, 30}
		set size of window 1 to {1512, 950}
	end tell
end tell

Les coordonnées partent du coin haut-gauche de ton écran principal. Un deuxième écran placé à gauche a donc des X négatifs (par exemple -1920), et un écran placé au-dessus a des Y négatifs (par exemple -1080).

✅ Astuce : demande à Claude de détecter automatiquement tes écrans avec NSScreen.screens() plutôt que d'écrire les coordonnées en dur. Comme ça le script marche aussi quand ton écran externe est débranché.

3. Lancer la musique Spotify

Spotify se pilote en AppleScript, mais le lien web ne fonctionne pas. Il faut convertir :

• Ce que Spotify te donne : https://open.spotify.com/track/2zYzyRzz6pRmhPzyfMEC8s
• Ce qu'il faut utiliser : spotify:track:2zYzyRzz6pRmhPzyfMEC8s

Tu prends juste l'identifiant après /track/ et tu ignores tout ce qui suit le point d'interrogation.

tell application "Spotify"
	pause
	set sound volume to 22
	play track "spotify:track:TON_ID_ICI"
end tell

⚠️ Le pause avant le play track n'est pas décoratif : sans lui, Spotify joue 2 à 3 secondes du morceau précédemment en file d'attente avant de basculer sur le tien. Autre bizarrerie : Spotify remet le volume à 100 tout seul en fin de chargement. Il faut vérifier et réappliquer ton volume après.

4. Jouer la voix

Deux pièges d'un coup avec le SDK ElevenLabs version 2 et supérieure :

• from elevenlabs import play importe un module, pas une fonction. Tu obtiens l'erreur 'module' object is not callable.
• Le lecteur intégré réclame ffmpeg, un logiciel supplémentaire à installer.

La bonne approche : écrire le MP3 sur le disque et le lire avec afplay, qui est déjà présent sur tous les Mac.

⚡ Mets la voix en cache, avec un nom de fichier basé sur un hash de la phrase. Résultat : la voix est générée une seule fois, puis elle part instantanément à chaque clap. Et si tu changes la phrase, elle se régénère toute seule.

5. Le taux d'échantillonnage du micro

Les MacBook échantillonnent à 48000 Hz, pas 44100 comme sur PC.

🔴 Un mauvais SAMPLE_RATE est la cause numéro 1 des claps non détectés. Si rien ne se passe quand tu claques, vérifie ça en premier.

5. La détection du clap, le vrai piège

C'est le point qui fait échouer la plupart des installations, et c'est aussi le plus intéressant.

Le problème : détecter un clap par le volume seul ne marche pas. Mesures réelles au micro d'un MacBook :

Les deux se chevauchent complètement. Si tu filtres par le volume, le script se déclenche tout seul dès que quelqu'un parle ou que la musique tourne. Inutilisable.

La solution : filtrer par la forme du son, pas par son volume. Un clap est une impulsion : il monte très fort et s'effondre en moins de 100 millisecondes. Une voix, elle, reste forte pendant toute la syllabe.

Concrètement, quand un pic dépasse le seuil, on ne déclenche pas tout de suite :

1. On note le niveau du pic.
2. On attend 100 ms.
3. On vérifie que le niveau est retombé sous 35 % du pic.
4. Si oui, c'est un clap. Sinon, c'est de la voix ou de la musique, on ignore.

À ça on ajoute deux garde-fous :

• Un plancher absolu (MIN_RMS autour de 0,28) pour ignorer les bruits de fond.
• Une fenêtre de temps entre les deux claps. Le projet d'origine utilise 0,12 à 0,35 seconde, ce qui est très serré : la plupart des gens claquent plus lentement. Élargis à 0,10 à 0,75 seconde, tu éviteras une longue séance de réglage.

6. La voix ElevenLabs

1. Crée un compte sur elevenlabs.io, le plan gratuit suffit.
2. Avatar en haut à droite, puis API Keys, puis Create API Key. Copie la clé, elle commence par sk_.
3. Menu Voices, onglet Default ou Premade. Clique sur les trois points à côté d'une voix, puis Copy Voice ID.

🚨 Le piège du plan gratuit : les voix de la Voice Library sont refusées par l'API avec une erreur 402, même si tu peux les écouter dans l'interface. Seules les voix natives (onglet Default / Premade) fonctionnent. Si tu copies l'identifiant depuis une URL du type elevenlabs.io/voices/..., c'est une voix de la Library : elle ne marchera pas.

Deux voix natives qui rendent bien en français :

• George : JBFqnCBsd6RMkjVDRZzb (voix masculine grave, très effet majordome)
• Daniel : onwK4e9ZLuTAKqWW03F9

Mets ensuite la clé et le Voice ID dans un fichier .env à la racine du projet :

ELEVENLABS_API_KEY=sk_ta_cle_ici
ELEVENLABS_VOICE_ID=JBFqnCBsd6RMkjVDRZzb
ELEVENLABS_MODEL_ID=eleven_multilingual_v2

🔒 Ajoute bien .venv/, .env et .cache/ dans ton fichier .gitignore. Sinon ta clé API part sur GitHub au premier push.

7. Les autorisations macOS

Deux autorisations à donner, sinon ça ne marchera pas :

• Micro : accepte simplement la demande qui apparaît au premier lancement.
• Accessibilité : nécessaire pour déplacer les fenêtres. Va dans Réglages système, puis Confidentialité et sécurité, puis Accessibilité, et coche ton terminal (Terminal, Ghostty, iTerm, Warp : celui que tu utilises). Quitte complètement le terminal et rouvre-le, sinon l'autorisation ne prend pas effet.

💡 Sans l'autorisation Accessibilité, tout le reste marche quand même : les apps s'ouvrent, la voix parle, la musique démarre. Seul le placement des fenêtres est perdu. Tu peux donc tester d'abord et régler ça après.

8. Lancer et régler

Lance une première fois avec le mode debug, c'est indispensable pour le réglage :

JARVIS_DEBUG=1 .venv/bin/python jarvis.py

À chaque son fort, tu verras une ligne de ce type :

[debug] pic=0.512  après 100ms=0.061  limite=0.179  → CLAP
[debug] pic=0.540  après 100ms=0.498  limite=0.189  → voix/musique (ignoré)

Quatre cas de figure et leur solution :

Une fois calé, relance sans le mode debug et c'est terminé.

9. Aller plus loin : plusieurs scènes

Une seule action au clap, c'est bien. Plusieurs, c'est nettement plus utile.

Le principe : chaque double clap joue la scène suivante, puis ça reboucle sur la première. Une scène, c'est simplement une phrase + un morceau + le fait d'ouvrir les apps ou non.

Un exemple qui marche très bien pour un créateur de contenu :

Tu tournes une vidéo : tu claques deux fois au début pour l'intro et ton setup, deux fois à la fin pour l'outro. Puis ça repart pour la vidéo suivante.

Les scènes se rangent dans un fichier config.json à la racine du projet, pour pouvoir en ajouter sans toucher au code :

{
  "JARVIS_SCENES": [
    {
      "nom": "réveil",
      "phrase": "Salut, tu as gagné 150 abonnés aujourd'hui, continue comme ça !",
      "spotify_uri": "spotify:track:XXXXXXXXXXXXXXXXXXXXXX",
      "ouvre_les_apps": true
    },
    {
      "nom": "outro",
      "phrase": "Merci à vous d'avoir regardé la vidéo, et à bientôt !",
      "spotify_uri": "spotify:track:YYYYYYYYYYYYYYYYYYYYYY",
      "ouvre_les_apps": false
    }
  ]
}

⚡ Le détail qui compte : fais générer les voix de toutes les scènes au démarrage du script, pas au moment du clap. Sinon la deuxième scène attend l'API ElevenLabs pendant plusieurs secondes avant de parler, et l'effet est cassé.

⚠️ Pense à mettre ouvre_les_apps à false sur les scènes suivantes. Sinon chaque clap rouvre et redéplace tes fenêtres, ce qui est très pénible en plein travail.

Idées de configuration

• Créateur de contenu : ton dashboard d'analytics, YouTube Studio, Notion, et une voix qui t'annonce combien de vidéos tu as en retard.
• Freelance : ton CRM, ta boîte mail, ton agenda, et un brief du type nombre de mails reçus et de calls bookés.
• Développeur : ton éditeur de code, la page des issues GitHub, Slack, et une musique qui met dedans.

🎁 Le bonus qui change tout : demande à Claude d'écrire la phrase de réveil avec de l'humour ou une pique personnelle. C'est ce qui transforme un gadget technique en truc que tu utilises vraiment tous les matins.

Dépannage rapide

• Erreur PEP 668 / externally managed : tu as oublié l'environnement virtuel. Refais l'étape 3.
• python: command not found : sur Mac c'est python3, ou mieux .venv/bin/python.
• Erreur 402 sur la voix : ta voix vient de la Voice Library. Prends une voix native.
• 'module' object is not callable : tu utilises le lecteur intégré d'ElevenLabs. Passe par afplay.
• Les fenêtres ne bougent pas : autorisation Accessibilité manquante, ou tu utilises le nom de l'app au lieu du nom du processus.
• Spotify joue le mauvais morceau : il manque le pause avant le play track.
• Rien ne se passe quand tu claques : vérifie le taux d'échantillonnage à 48000, puis lance en mode debug.

Ressources

• 📦 Dépôt GitHub : github.com/hectorg2211/jarvis
• 🔊 Voix de synthèse : elevenlabs.io