Commencer à développer sur Karaoke Mugen
Pour bien commencer, il vous faut de bons outils. Ce guide est prévu pour Windows mais ne diffère pas beaucoup si vous êtes sous Linux ou macOS
On donne un moyen d'installer les applications nécessaires mais n'oubliez pas que vous pouvez aussi choisir les outils avec lesquels vous avez le plus l'habitude de travailler, par exemple en remplaçant Fork par Gitkraken ou git Bash par le WSL.
Installer git / fork
- Récupérez git
- gitAhead est un bon client graphique multiplateforme
- Fork est un client graphique très pratique pour git, open source et multiplateforme, mais payant.
En général utiliser git bash (fourni avec git) est un bon terminal.
Installer Visual Studio Code
Il y a de bonnes extensions à installer :
- Beautify
- better Comments
- ES Lint (indispensable car il va sous-ligner les petits défauts de code pour vous comme l'indentations, les ; de fin de commande, etc. qui vont vous faciliter la vie grandement !
- gitignore
- GitLens (pour éventuellement faire vos commits depuis VSCode ou voir facilement qui a écrit cette ligne de code)
- markdownlint
- Node.js modules intellisense (auto-complétion des noms de modules JS)
- npm intellisense (auto-complétion NPM)
- SQL Beautify
- vscode-icons
- YAML
Installer et préparer PostgreSQL
L'installeur Windows de EnterpriseDB fera parfaitement l'affaire car il installe PostgreSQL en tant que service sous Windows et il est livré avec pgAdmin pour s'occuper de la base au besoin.
Une fois installé, vous devrez créer un user superadmin. Lancez la commande dans le dossier bin
de votre dossier PostgreSQL (par défaut C:\Program Files\PostgreSQL\12\bin
).
Attention, l'extension unaccent qui est utilisée plus loin n'est supportée que si votre serveur PostgreSQL est suffisemment récent (à ce jour, > 9.3 ). Mettez d'abord, si nécessaire, votre serveur à jour.
createuser -h localhost -P -s postgres
Si ça vous dit que le rôle existe déjà, tant mieux. Sinon entrez le mot de passe musubi
.
Connectez-vous avec ce user postgres via :
psql -U postgres
Soit il vous demandera votre mot de passe définit plus haut soit rien du tout si le user existait déjà.
On va créer le user et base de données de KM App :
CREATE DATABASE karaokemugen_app ENCODING 'UTF8';
CREATE USER karaokemugen_app WITH ENCRYPTED PASSWORD 'musubi';
GRANT ALL PRIVILEGES ON DATABASE karaokemugen_app TO karaokemugen_app;
On doit ajouter une extension à la base, donc :
\c karaokemugen_app
Le prompt change pour indiquer qu'on est sur la base nouvellement crée. Puis :
CREATE EXTENSION unaccent;
Puis \q
pour quitter.
Installer NodeJS
Installez NodeJS depuis son site web. Normalement il faut prendre la dernière version LTS, sauf cas contraire mais c'est uniquement quandon fait des tests de montée de version de Node
Installer Yarn
Yarn est un lanceur et gestionnaire de packages comme npm. Installez-le.
Cloner le dépôt Karaoke Mugen
Faites-vous un dossier par exemple C:\dev
sous Windows.
Ouvrez votre terminal favori et allez dans le dossier en question pour taper :
git clone https://lab.shelter.moe/karaokemugen/karaokemugen-app.git
Vous pouvez aussi cloner en SSH si vous préférez. Assurez-vous d'avoir une clé SSH et de l'indiquer dans votre profil sur Gitlab.
Puis allez dans le dossier crée par le clone karaokemugen-app
.
Configuration de git
Pour vous faciliter la tâche on a préconfiguré git pour vous. Pour activer ça, lancez
yarn gitconfig
Ça va activer diverses options :
- Afficher le diff des sous-modules
- Faire en sorte que les pull/fetch/status et push aillent récursivement dans les sous-modules.
Pour push vos commits vous aurez besoin du statut de Développeur sur Gitlab, demandez-le à AxelTerizaki sur Discord. Vous pouvez également faire un fork chez vous et proposer des merge request si ça vous va mieux
Vous aurez également besoin, si vous n'utilisez pas SSH, d'un token au moment de push. Vous pouvez générer ce token depuis votre page paramètres de gitlab dans la section "Access Token" / "Jetons d'accès"
Installation et configuration Node
Tout est automatisé, il vous suffit de taper
yarn setup
setup
est en fait une commande qui va faire plusieurs choses :
- L'installation des dépendances node pour les 3 parties sus-citées (
yarn install
dans les 3 dossiers) - La transpilation du code Typescript/React en code JS utilisable via
yarn build
dans chaque dossier.
Selon ce que vous modifiez, utilisez bien les bonnes commandes dans le bon dossier. yarn setup
peut être long et pas toujours nécessaire.
Installer les dépendances binaires
Vous aurez besoin de ffmpeg et mpv. Téléchargez-les et dézippez-les dans le dossier app/bin
(creez-le si nécessaire)
Récupérer une base de karaokés complète
Allez dans app
et clonez Karaokebase :
git clone https://lab.shelter.moe/karaokemugen/karaokebase.git
Les médias
Les médias prennent plusieurs centaines de giga-octets mais ne sont pas nécessaires pour faire du dev. Sauf si vous bossez sur le player, dans ce cas il est recommandé de se rabattre sur les samples fournis.
Ils peuvent être mis à jour via les scripts updateMedias.cmd ou updateMedias.sh selon votre système, ou en lançant KM avec --updateMedias
.
Configurer KM
Copiez database.sample.json
dans app
et renommez-le database.json
Editez-le :
{
"sql-file": true,
"defaultEnv": "prod",
"prod": {
"driver": "pg",
"user": "karaokemugen_app",
"password": "musubi",
"host": "localhost",
"database": "karaokemugen_app",
"port": 6559,
"schema": "public",
"superuser": "postgres",
"superuserPassword": null,
"bundledPostgresBinary": true
}
}
Si vous avez déjà un postgresql d'installé, modifiez : port: 5432
et bundledPostgresBinary: false
.
Créez un fichier config.yml
dans app
avec le contenu suivant :
Online:
Stats: false
ErrorTracking: false
System:
Repositories:
- Name: kara.moe
Online: true
Enabled: true
Path:
Karas:
- karaokebase/karaokes
Lyrics:
- karaokebase/lyrics
Medias:
- karaokebase/medias
Series:
- karaokebase/series
Tags:
- karaokebase/tags
Avec cette configuration KM ira chercher tous les karas de votre karaokebase que vous avez cloné tout à l'heure depuis le git.
Aussi, les stats ne seront pas envoyées afin de ne pas embrouiller KM Server avec des stats faussées par vos essais.
Lancement
musique de Gundam
Une fois que tout est prêt, on peut lancer via
yarn start
start
va transpiler KM du Typescript au Javascript à chaque lancement. Cela peut prendre de nombreuses secondes mais votre programme lancé sera toujours à jour.
Annexes
Structure du projet KM
KM est découpé en trois grandes parties :
- Deux frontends React :
systempanel
est le panneau Système de KM, qui permet toute la gestion de l'application. Ajout/suppresion de karaokés, et d'autres tâches. On utilise antd comme framework. C'est adapté à des outils de gestion.frontend
est l'interface mobile et PC dédiée à la gestion d'une session karaoké, que ça soit pour les opérateurs de karaoké ou leur public.- Un backend NodeJS dans
src
.
Pour ces trois parties, nous utilisons Typescript pour gérer le typage de l'application.
Il y a également un dossier migrations
contenant les migrations SQL servant à gérer la structure de la base et ses mises à jour.
La librairie Karaoke Mugen
Accessoirement KM utilise une librairie de fonctions partagée avec KM Server et sobrement appelée KM Lib. Cette lib se trouve dans src/lib
et est un sous-module git. Pour comprendre comment ça marche, cette petite doc est très bien. Un sous-module git nous permet notamment de versionner la librairie, d'en faire des branches, bref d'avoir du code commun réutilisable.
La lib est mise à jour automatiquement par un pull
de l'app KM, mais si jamais vous y touchez, il faudra penser à commit
et push
dans le dossier src/lib
avant d'ajouter ce dernier à KM App et de commit
et push
sur KM App. La doc sus-citée vous donnera plus d'informations pour comprendre les sous-modules git.
La lib contient notamment des fonctions pour :
- L'accès à la base de données postgresql ainsi que pour gérer le filtre de la liste des karaokés
- La définition des formats de fichiers kara, séries, tags...
- La génération de la base de données à partir des fichiers de karaokebase
- L'interfaçage avec un gitlab
- La création de fichier karaoké
- Des types communs à KM Server et KM App
- Des utilitaires divers comme :
- une barre de progression
- Manipulation de fichiers ASS
- Manipulation de dates
- ffmpeg (pour lire les infos d'une vidéo ou calculer le gain audio)
- Accès aux fichiers (lecture, écriture, etc)
- Journalisation (logger)
- Gestion de Passport (qui permet d'authentifier les utilisateurs)
- Génération des prévisualisations de vidéos
- Validateurs des données entrantes (contrôles)
- Websockets et système PubSub interne
Structure du backend
Ceci est un tour d'horizon basique du backend :
- Tout démarre dans
index.ts
, il suffit de suivre la fonctionmain()
. - Le dossier
components
contient les principaux modules de KM, par exemple son moteur, l'init du frontend et mpv, son player vidéo - Le dossier
electron
contient tout le code relatif à l'application Electron et son interface graphique - Le dossier
services
contient tout le code applicatif et la logique. Manipulation des playlists, des karas, du player, et de tout autre sous-système de KM. Lesservices
fournissent des fonctions auxcontrollers
et piochent leurs données via les fonctions dedao
. - Le dossier
controllers
contient toutes les routes d'API appellées par le frontend de KM. Les routes d'API appellent les fonctions desservices
. - Le dossier
dao
contient toutes les fonctions faisant entrer et sortir des données de Karaoke Mugen : écrire et lire dans la base de données, dans les fichiers, etc. - Le dossier
locales
contient des traductions de quelques phrases et mots utilisés dans KM. - Le dossier
types
contient toutes les définitions de types utilisés dans l'application. - Le dossier
utils
contient une myriade d'utilitaires appelés à différents endroits : gestion de la configuration, de l'état, les constantes, les paramètres par défaut, le téléchargement, la manipulation de git, twitch, ou postgresql, etc.
Versions
La numérotation des versions suit le semver classique : majeure.mlineure.sous-version
- 2.1.0 est une version majeure de la base de code 2.x.
- 2.2.1 est une correction de la 2.2.
- 3.0.0 est une nouvelle version majeure.
De plus chaque version a un nom de code. Chaque version majeure est un personnage féminin d'animation japonaise, et chaque version mineure un adjectif portant la même première lettre que l'héroine. Exemples :
- Akari Amoureuse
- Belldandy Bolchévique
- Chitoge Chatoyante
- Finé Fiévreuse
- Finé Fantastique
- etc.
On se débrouille pour trouver un fond d'écran pour chaque version.
Structure du git
Il y a deux branches :
master
est la branche stable. Si on a un fix à faire sur une version actuellement stable on fera le fix sur cette branche. On mergenext
dansmaster
lors des versions majeures.next
est la branche de développement. C'est ici qu'on fera toute modification ou qu'on fera un merge d'une branche de fonctionnalité.
Lorsque l'on travaille sur une issue, on lui crée une branche dédiée. Gitlab s'en occupe pour nous en créant une merge request et une branche automatiquement en appuyant sur le bouton adéquat sur la page de l'issue. Pensez à indiquer next
comme branche source quand vous le faites.
Créer une nouvelle migration
On utilise l'outil postgrator. S'il n'est pas installé correctement par yarn :
npm install -g postgrator
Puis lancement via pour effectuer les migrations sans Karaoke Mugen :
yarn postgrator
Pour créer une migration il faut créer notamment deux fichiers SQL dans migrations
qui s'appellent chacun do
et undo
. Regardez d'autres exemples fournis.
Pensez à écrire votre migration en étape par étape puis à écrire les migrations de retour arrière (down) dans un brouillon avant de les mettre dans les fichiers .sql et de les tester sur KM.