Installer l'app OIQ — guide Mac, Windows, Linux

L'app OIQ (Objective Intelligibility & Quality) calcule, à partir d'un enregistrement stéréo avec/sans aide auditive, des métriques objectives d'intelligibilité et de qualité : HASPI v2, STOI, ESTOI, SIIB^Gauss côté intelligibilité ; HASQI v2, HAAQI, EDI et PESQ côté qualité. Elle tourne entièrement en local sur votre machine : c'est une application R / Shiny qui appelle des bibliothèques Python (projet Clarity, pystoi, pesq, pySIIB) via le paquet reticulate.

Ce guide couvre l'installation complète sur macOS, Windows et Linux, en six étapes. Aucune compétence en programmation n'est nécessaire : chaque étape est un téléchargement ou une commande à copier-coller.

Avant de commencer — ce qu'il vous faut :

• environ 30 minutes (dont ~10 min de téléchargements/installations automatiques) ;
• environ 5 Go d'espace disque (l'environnement Python inclut de grosses bibliothèques de calcul) ;
• idéalement 8 Go de RAM ou plus et un processeur multi-cœurs (l'app parallélise les calculs) ;
• les droits d'administrateur sur la machine (pour installer R, RStudio et Python).

Étape 1 — Installer R

R est le langage dans lequel l'app est écrite. Installez la dernière version stable depuis le site officiel (CRAN) :

macOSR pour Mac

Rendez-vous sur cran.r-project.org/bin/macosx et téléchargez le paquet .pkg correspondant à votre puce :

Apple Silicon (M1, M2, M3, M4…) : le fichier « arm64 » ;
Intel : le fichier « x86_64 ».

(En cas de doute : menu Pomme → « À propos de ce Mac » : la ligne « Puce » indique Apple M… ou Intel.) Double-cliquez le .pkg et suivez l'assistant.

WindowsR pour Windows

Rendez-vous sur cran.r-project.org/bin/windows/base, cliquez « Download R for Windows », lancez le .exe et acceptez les options par défaut.

LinuxR pour Ubuntu / Debian

Dans un terminal :

Terminal

sudo apt update
sudo apt install -y r-base r-base-dev

Si votre distribution fournit un R trop ancien (< 4.3), ajoutez le dépôt CRAN en suivant les instructions officielles pour Ubuntu.

Étape 2 — Installer RStudio

RStudio est l'interface graphique depuis laquelle vous lancerez l'app. Téléchargez RStudio Desktop (gratuit) sur posit.co/download/rstudio-desktop — le site détecte votre système et propose le bon installateur (Mac, Windows ou Linux). Installez-le comme n'importe quelle application.

Étape 3 — Installer Python 3.11 et les outils de compilation

Les métriques (HASPI, PESQ, SIIB…) sont calculées par des bibliothèques Python. L'app a été validée avec Python 3.11 : installez précisément cette version, même si une plus récente existe. Deux des bibliothèques (pesq et pySIIB) sont compilées localement lors de l'installation : il faut donc aussi un compilateur C et l'outil Git. Tout est gratuit et détaillé ci-dessous par système.

macOSPython + outils sur Mac

Téléchargez l'installateur Python 3.11.9 (« macOS 64-bit universal2 installer ») sur python.org, puis lancez-le (options par défaut).
Installez les outils de développement Apple (compilateur + Git en un paquet). Ouvrez l'application Terminal et tapez :

Terminal

xcode-select --install

Une fenêtre s'ouvre : cliquez « Installer » et laissez finir (quelques minutes). Si le message indique que les outils sont déjà installés, c'est parfait, passez à la suite.

WindowsPython + outils sur Windows

Téléchargez l'installateur Python 3.11.9 (« Windows installer 64-bit ») sur python.org. Au lancement, cochez impérativement « Add python.exe to PATH » en bas de la première fenêtre, puis « Install Now ».
Installez Git pour Windows depuis git-scm.com (options par défaut).
Installez le compilateur Microsoft : téléchargez « Build Tools pour Visual Studio » sur visualstudio.microsoft.com, lancez-le et cochez la charge de travail « Développement Desktop en C++ » (l'installation est volumineuse, ~6 Go — c'est normal).
Redémarrez l'ordinateur une fois les trois installations terminées.

LinuxPython + outils sur Ubuntu / Debian

Ubuntu récent fournit Python 3.12 par défaut ; installez la 3.11 via le dépôt deadsnakes :

Terminal

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3.11-dev build-essential git

(Sur Debian, ou si le PPA n'est pas disponible, installez le paquet python3.11 de votre distribution ou compilez depuis python.org ; l'essentiel est de disposer de python3.11, de venv et d'un compilateur.)

Étape 4 — Télécharger l'app

Téléchargez l'archive de l'app : App_OIQ_R_parallel_diffusion.zip (~40 Ko).

Décompressez-la (double-clic) puis déplacez le dossier obtenu App_OIQ_R_parallel vers un emplacement simple et permanent, par exemple dans Documents. Évitez un dossier synchronisé partiellement en ligne ou un chemin réseau. Le dossier doit contenir notamment app.R, setup.R, requirements.txt et le sous-dossier engine/.

Étape 5 — Configurer l'app (une seule fois)

Ouvrez RStudio, puis indiquez-lui le dossier de l'app : menu Session → Set Working Directory → Choose Directory… et sélectionnez le dossier décompressé à l'étape 4.

Dans la console R (panneau en bas à gauche), tapez ensuite :

Console R

source("setup.R")

Ce script fait tout le reste automatiquement :

il installe les paquets R nécessaires (Shiny, reticulate, future…) ;
il crée un environnement Python isolé nommé oiq-py (votre Python système n'est pas modifié) ;
il y installe les bibliothèques de métriques (pyclarity, pystoi, pesq, pySIIB) dans les versions exactes validées, puis vérifie qu'elles se chargent.

Comptez 5 à 15 minutes selon la connexion ; la compilation de pesq et pySIIB fait défiler beaucoup de texte, c'est normal. À la fin, vous devez voir :

OK. Virtualenv 'oiq-py' pret (pyclarity + pystoi + pesq + pysiib importes).
Lancez l'app : shiny::runApp("app.R")

Si le script se termine sur un avertissement (« Setup Python ÉCHOUÉ »), ne continuez pas : consultez la section Dépannage ci-dessous, corrigez, puis relancez simplement source("setup.R") — le script reprend où il en était.

Étape 6 — Lancer l'app

Toujours dans RStudio, avec le dossier de l'app comme répertoire de travail :

Console R

shiny::runApp("app.R")

L'app s'ouvre dans une fenêtre (ou votre navigateur). Pour les lancements suivants : ouvrez RStudio, refaites Session → Set Working Directory, et relancez cette même commande — l'étape 5 n'est plus jamais nécessaire.

Premier calcul en mode parallèle : au démarrage d'une analyse sur plusieurs cœurs, chaque cœur compile une fois le code de calcul (numba). L'écran peut rester 1 à 2 minutes sans activité visible : ce n'est pas un blocage. Les analyses suivantes démarrent immédiatement.

Machines à 8 Go de RAM ou moins : limitez le sélecteur « Cœurs » à 2–4, chaque cœur chargeant sa propre copie de Python en mémoire.

Dépannage

Symptôme	Cause probable et solution
`ModuleNotFoundError: No module named 'clarity'` au lancement de l'app	L'environnement Python `oiq-py` n'existe pas ou est incomplet. Refaites l'étape 5 (`source("setup.R")`) et lisez son message final.
`Suitable Python installation … not found` pendant le setup	Python 3.11 n'est pas détecté. Vérifiez l'étape 3 (sous Windows : la case « Add python.exe to PATH » était-elle cochée ? Sinon réinstallez Python en la cochant), fermez et rouvrez RStudio, relancez le setup.
Échec pendant l'installation de `pesq` ou `pysiib` (messages « error » mentionnant compiler, cl.exe, gcc ou git)	Compilateur ou Git manquant : reprenez l'étape 3 pour votre système (Mac : `xcode-select --install` ; Windows : Build Tools C++ et Git ; Linux : `build-essential git`), redémarrez la machine, relancez le setup.
Setup interrompu, environnement suspect, comportement incohérent	Repartez de zéro proprement : `reticulate::virtualenv_remove("oiq-py")` puis `source("setup.R")`.
L'analyse échoue au découpage du fichier	Le signal à analyser doit être un `.wav` stéréo (gauche = sans aide, droite = avec aide) ; un fichier mono est refusé. Idéal : 44,1 kHz / 24 bits PCM.

Bonnes mesures ! Pour toute question sur l'installation, laissez un commentaire sous cet article en précisant votre système (Mac/Windows/Linux) et le message d'erreur complet.