J’utilise régulièrement ruby-taglib. Malheureusement, certains bugs empêchent son utilisation avec ruby 1.9. Après avoir tenté, avec plus ou moins de succès, de corriger ces bugs, j’ai décidé de réécrire cette bibliothèque. La version originale est basée sur ruby/DL, bibliothèque que je n’ai jamais utilisée. Je profite de cette réécriture pour proposer une série d’articles sur la manière d’adapter une bibliothèque C.

Préparation

Je développe pour l’instant sous ubuntu 10.04 (je terminerai sûrement ces articles sous la version 10.10). J’ai installé taglib, ruby et rdoc soit les paquets debian suivant : libtagc0, libtagc0-dev, ruby, ruby-dev, rdoc.

Hiérarchie

La commande tree présente l’arborescence de mon répertoire de travail.

Le fichier extconf.rb, écrit en ruby, permettra de préparer les sources en vue de compiler la bibliothèque. Le fichier lib/taglib2.rb, lui aussi écrit en ruby, est le fichier lu par l’interpréteur ruby lors de l’appel à require « taglib2″ qui chargera notre future bibliothèque.Le fichier taglib2.c, écrit en C, contiendra les méthodes qui permettent d’interfacer taglib.

Ruby

Dans un premier temps, j’utiliserai seulement le langage ruby. J’écris donc les premières lignes de code dans le fichier lib/taglib2.rb.

Une constante nommée VERSION est définie comme un tableau contenant 3 entiers. D’ores et déjà, je peux tester mon code grâce à irb, un interpréteur ruby en ligne de commande. La bibliothèque n’étant pas encore installée, j’utilise un chemin relatif pour y accéder.

Interface ruby/C

Exceptions

Nous nous intéressons enfin au fichier taglib2.c. Nous définissons, tout d’abord, les différents types d’exceptions qui peuvent être levés par la bibliothèque.

Les fichiers nécessaires au développement de la bibliothèque sont tout d’abord inclus puis nous déclarons des variables de type VALUE. Ce type est utilisé pour toute variable représentant un objet du langage ruby. Les noms de variables représentant des exceptions sont généralement préfixés par la lettre e. Pour les modules, la lettre m est utilisée, pour les classes, la lettre c.
Il s’agit d’une convention et non d’une règle. Finalement, on retrouve la fonction Init_taglib2 qui (re)définit le module TagLib ainsi que 4 classes descendant de la classe ruby Exception représentée en C par la variable rb_eException.

Le code suivant, écrit en ruby, est équivalent à la définition donnée en C de l’exception TagLib::BadPath

Compilation

Afin de compiler notre bibliothèque, nous devons créer un fichier Makefile. La bibliothèque mkmf nous facilite le travail.

Dans le fichier extconf.rb, la présence des fichiers « header » de ruby et de taglib sont vérifiées ligne 3 et 4. La ligne 6 permet de créer le fichier Makefile du projet taglib2. Lors du chargement d’une interface ruby/C, la fontion appelée est de la forme Init_NomDuProjet,c’est pourquoi l’unique fonction du fichier taglib2.c s’appelle Init_taglib2. Il s’agit de l’équivalent de la fonction main d’un programme C traditionnel.

Après avoir créer le fichier Makefile, compilons.

Un bibliothèque dynamique taglib2.so vient de faire son apparition. Ruby permet de charger directement ce type de bibliothèque. Nous ajoutons donc l’instruction (require « taglib2.so ») de chargement dans le fichier lib/taglib2.rb.

Test

Nous testons notre code sous irb.

J’ajoute tout d’abord le répertoire courant et le répertoire lib dans les chemins vérifiés lors du chargement d’un fichier afin que les appels à require « taglib2″ et à require « taglib2.so » n’échouent pas. Cette astuce ne sera plus nécessaire une fois la bibliothèque installée. On vérifie que les constantes définies dans les fichiers sources lib/taglib2.rb et taglib2.c sont accessibles.

Conclusion

Lors de ce premier billet, j’ai mis en place les différents éléments (bibliothèques, fichiers) qui seront nécessaires à l’interface ruby de taglib. Nous avons, déjà, réussi à obtenir un code fonctionnel. Il nous reste à porter les fonctions proposées par taglib afin de pourvoir accéder, en ruby, aux tags de fichiers musicaux.
À la prochaine.

Je ne suis pas un spécialiste du langage C, si vous avez des suggestions à faire sur mon code
commentez ce billet.

Addendum

Je rajoute la liste des billets faisant suite à celui-ci :

• billet 2,
• billet 3,
• billet 4,
• billet 5.

Un assistant explique le fonctionnement de ZiK lors d’une nouvelle installation. Il permet aussi une configuration rapide du logiciel. Il est disponible via le menu aide.
L’édition de la liste de lecture et la recherche de pistes audio sont maintenant intégrées à la fenêtre principale.
La vue compact permet d’afficher un plus grand nombre de pistes audio dans la liste de lecture.
ZiK supporte maintenant ruby-taglib2 et les nouvelles versions de rghk (0.2) et de gtk (2.22).
La traduction française a été mise à jour.
Pour plus d’informations, voyer le fichier ChangeLog.

Téléchargez ZiK sur developpez.com.

Je vais présenter ici quelques fonctions utiles. Pour des questions de faciliter, j’ai créé deux nouvelles méthodes pour le module TagLib bien qu’elles n’aient rien avoir avec taglib.

Utiliser un bloc

La méthode TagLib.block ne prend aucun paramètre, mais un bloc doit lui être fourni. Elle exécute ce bloc en lui passant comme argument l’objet TagLib et retourne le bloc sous la forme d’un Proc.

Voici la fonction implémentant ce comportement.

rb_yield permet d’appeler le bloc passé à la méthode alors que rb_block_proc permet de le manipuler sous la forme d’un Proc.

Utiliser des paramètres optionnels

Je propose d’écrire l’équivalent de code écrit en ruby.

Le dernier argument lors de la déclaration de la méthode TagLib.n vaut -1 ce qui indique que la méthode ne possède pas un nombre d’arguments fixees. La fonction rb_scan_args permet de récupérer de manière propre les paramètres passés à la méthode. Le troisième argument de cette fonction est une chaîne de caractère représentant deux chiffres. Le premier indique le nombre de paramètres obligatoires, le second indique le nombre de paramètres optionnels.

TagLib.n peut donc être appelée avec un paramètre ou sans. Si aucun argument n’a été passé (tab=nil), tab est initialisé en créant un tableau contenant deux objets String. On vérifie ensuite que tab appartient à la classe Array ou s’en rapproche (duck typing). rb_funcall permet d’appeler une méthode (deuxième argument) d’un objet (premier argument) avec un certain nombre (troisième argument) de paramètres (arguments suivant). rb_intern permet d’obtenir la méthode à partir d’une chaîne de caractères.
La fonction n1 est ensuite appelé pour chacun des éléments du tableau grâce à rb_iterate. LA méthode retourne, finalement, le premier élément de tab, la macro RARRAY permettant d’accéder à la structure interne d’un objet de la classe Array, le champ ptr permettant d’accéder aux éléments.

Liens utiles

Quelques liens qui m’ont aidé à écrire des extensions pour ruby en C :
le fichier README.EXt fourni avec ruby,
ruby-doc.
En ce qui concerne taglib :
l’exemple dans les sources de taglib,
le fichier bindings/c/tag_c.h.

Sources

Le code, présenté dans ces billets, implémentant le module, TagLib est téléchargeable ici.

Conclusion

Cette série d’articles est finie. J’espère qu’ils vous seront utiles.

Documentation

Commenter

Pour documenter les méthodes de la classe TagLib::File, il suffit de commenter les différentes fonctions les implémentant.

La méthode title permet d’obtenir le titre d’une piste. On l’indique en commentaire juste avant la fonction file_get_title.

Par défaut, les paramètres d’une méthode sont nommés p1, p2, …. Pour la méthode title=, on utilise l’instruction call-seq: pour afficher le texte title=title (au lieu de title=(p1)).

La méthode initialize ne devrait jamais être appelée directement depuis un code ruby. On utilise l’instruction :nodoc: pour indiquer que la méthode ne doit pas apparaitre dans la documentation.

J’indique que je ne désire pas commenter le module TagLib en plaçant un commentaire vide afin d’éviter que rdoc utilise un commentaire non-désiré.

Dans le fichier lib/raglib2.rb, j’ajoute la directive :main: afin que la page initiale de la documentation pointe sur la classe TagLib::File.

Bizarrement, cette directive ne semble pas fonctionner si elle est placée dans le fichier taglib2.c.

Produire la documentation

Le fichier doc/index.html est créé.

Conclusion

Rendez-vous pour le dernier billet où j’introduirai quelques concepts que je n’ai pas utilisé dans le module TagLib.

Jouer avec les tags

Accéder au tag

La structure tgFileData contient un champ tag qui permettra d’accéder au tag du fichier. Il a été initialisé avec la valeur NULL. La fonction file_tag retourne la valeur de ce champ après l’avoir complété au besoin.

La macro Data_Get_Struct permet d’accéder à la structure tgFileData de notre objet. Si le champ tag n’est pas rempli, on récupère sa valeur grâce à la fonction taglib_file_tag de la bibliothèque taglib. Une exception est levée dans le cas où cette dernière fonction faillirait. La valeur du champ est finalement retournée.

Obtenir le titre d’une piste audio

Afin d’obtenir le titre contenu dans un tag, une méthode title est ajoutée à la classe TagLib::File, dans la fonction Init_taglib2.

La fonction file_get_title implémente la méthode TagLib::File#title

La valeur du titre est obtenu grâce à la fonction taglib_tag_title qui prend la valeur du champ tag de la structure interne tgFileData. La fonction rb_str_new2 transforme cette valeur obtenue sous la forme d’un pointeur sur chaîne de caractères en un objet ruby de la classe String. La mémoire allouée par taglib pour cette opération est libérée avant de retourner l’objet.

Modifier le titre d’une piste audio

La méthode TagLib::File#title=, prenant un argument, est ajoutée.

La fonctionfile_set_title utilise la bibliothèque taglib pour modifier le tag. Une nouvelle fois, la macro StringValuePtr est utilisée pour convertir une variable du type VALUE vers le type char *. Une fonction implémentant une méthode accessible depuis ruby doit obligatoirement retournée une valeur du type VALUE. J’ai choisi ici de retourner la chaîne de caractère passée en argument.

Il me semble que traditionnellement les méthodes du type variable= retourne l’argument alors que les méthodes du type set_variable retourne l’objet. La troisième possibilité étant de retourner nil.

Sauvegarder les modifications

Après avoir modifié le titre à l’aide de la méthode vue au précédent paragraphe, il faut écrire cette modification dans le fichier audio.

La méthode TagLib::File#save permet cette écriture. La méthode retourne true si l’opération est réussie ou false.

La fonction taglib_file_save réalise l’écriture après avoir accédé au champ file de la structure interne de notre objet ruby.

Tester le code

Voici le contenu du fichier taglib2.c

Après avoir recompilé, nous pouvons tester les méthodes ajoutées dans cet article.

Conclusion

Nous avons vu comment accéder au titre d’une piste audio. Accéder aux autres propriétés (auteur, album, etc) n’est pas plus difficile. Je ne développerai pas cet aspect. Les sources du code complet seront cependant mis à votre disposition lors du dernier article. Le prochain article devrait parler de l’aspect documentation.

Addendum

Afin que notre bibliothèque soit correctement liée à taglib lors de la compilation, il faut ajouter la ligne have_library(‘tag_c’) || exit(1) au fichier extconf.rb, juste avant d’invoquer la création du Makefile.

Créer un objet appartenant à la classe TagLib::File

Ajouter une classe File

Après avoir déclaré une nouvelle variable de type VALUE (cFile), je définis une nouvelle classe nommée File appartenant au module TagLib. Elle hérite de la classe Objet (classe mère de toutes les classes en ruby).

Après avoir recompilé notre bibliothèque, je peux créer un objet de type TagLib::File, cette classe ayant héritée de la méthode Objet.new.

Redéfinir la méthode new

Dans la fonction Init_taglib2, je redéfinis la méthode de classe new (et non une méthode d’instance). C’est pourquoi j’utilise rb_define_singleton_method et non rb_define_method. Cette fonction prend quatre arguments : l’object pour lequel la méthode va ếtre (re)défini, le nom de la méthode, la fonction écrite en C à appeler, le nombre d’aguments passés à la fonction.

Voici la fonction file_new qui redéfinit TagLib::File.new.

La méthode new est appelée avec un seul argument qui est une chaîne de caractère ruby représentant un chemin vers un fichier audio. Cependant, la function file_new possède un argument supplémentaire : le premier qui représente l’objet auquel s’applique la méthode.
La fonction taglib_file_new permet de créer une structure qui représente un fichier audio pour la bibliothèque taglib. Elle requière, comme argument, un pointeur sur une chaîne de caractère C obtenu grâce à la macro StringValuePtr.
La variable data est une structure qui représentera un objet de type TagLib::File au niveau du langage C. Elle est composée de trois champs représentant le fichier audio (file), le tag associé au fichier (tag) et les propriétés audio du fichier (audio). Après avoir alloué la mémoire nécéssaire (grâce à la macro ALLOC) et initialiser ses différents champs, cette structure est transformée en object ruby grâce à l’aide de la macro Data_Wrap_Struct. Cet object rbData appartient à la classe TagLib::File (représenté par la variable cFile). Lorsque l’objet est détruit, la fonction free_tgFileData est appelée.
Enfin, l’objet est initialisé (rb_obj_call_init).

Écrire la méthode initialize

La méthode new appelle la méthode initialize qui, comme son nom l’indique, s’occupe d’initialiser l’objet, en particulier ses variables d’instance.
Cette dernière méthode est déclarée dans la fonction Init_taglib2.

Ici, la méthode initialize se borne à valoriser la variable d’instance @path.

Libérer la mémoire

Lorsque le ramasse-miettes de ruby détruit un object de type TagLib::File, il utilise la fonction indiquée lors de l’appel à la macro Data_Wrap_Struct, pour libérer la mémoire allouée à cet objet.

Code

Voici l’ensemble du code :

Tester le code

Après une recompilation, on vérifie que la méthode TagLib::File.new est correctement appelée depuis l’interpréteur irb.

Conclusion

Lors de ce deuxième billet, nous avons interfacé une structure C avec un objet ruby, représentant un fichier audio. Dans le prochain billet, nous écrirons les méthodes qui permettent d’accéder au tag de ce fichier.

À la découverte de linux

Suite à quelques utilisations sporadiques de différentes distributions linux, j’ai réellement découvert linux en installant ubuntu 5.10. Après avoir réglé quelques difficultés, je trouve mes marques et retrouve certains logiciels que j’utilisais sous windows. Un seul logiciel me manque vraiment, il s’agit de DéKiBulle un lecteur audio que j’apprécie particulièrement.

À la découverte de ruby

Plus pour m’amuser que pour autres choses, en 2007, je commence à développer un petit script, en bash, nommé ZiK qui me permet de lire mes fichiers audio. Puis je décide de développer une interface graphique et un lecteur audio digne de ce nom dans l’idée d’apprendre un langage de programmation. Après avoir hésité entre ruby et python, j’opte pour ruby. Si j’avais su que python est livré en standard dans la plupart des distributions, mon choix aurait peut-être été différent. Cependant, je ne regrette pas mon choix, je trouve ruby plus sexy (avis totalement orienté par mon expérience).

À la (re)découverte des paquets debian

J’ai découvert les paquets debian côté « fabricant » lorsque j’ai voulu distribuer ZiK sous la forme d’un paquet debian.
J’ai procédé en plusieurs étapes.
J’ai tout d’abord, tout simplement, invoquer dpkg-deb –build sur une arborescence locale imageant une installation de ZiK en prenant soin d’ajouter un dossier DEBIAN contenant les fichiers control et changelog.
J’ai ensuite écrit un fichier rules afin de pouvoir publier un paquet sur mon ppa (debuild et pbuilder sont devenus alors très utiles). La qualité de paquets disponibles sur ce dernier laissent à désirer.
La troisième étape implique la création de paquets plus propres qui seront, si possible, intégrés à debian.

Contribuer à debian

Afin de pouvoir définir des raccourcis clavier globaux pour mon application ZiK, je développe une bibliothèque nommée rghk (ruby global hotkeys). La construction de son paquet debian étant relativement aisé, je me suis proposé pour inclure cette bibliothèque. Elle est maintenant disponible pour debian unstable (ainsi que sous ubuntu 10.10) sous le nom libglobalhotkeys-ruby. Elle ne devrait cependant pas être incluse dans squeeze car son arrivée dans les dépôts à précéder le gel seulement de quelques heures.
Je remercie Lucas Nussbaum de l’équipe pkg-ruby-extra pour son aide lors du processus d’inclusion.
Ayant réussi mon galon d’essai, ZiK devrait prochainement rejoindre debian (en version 0.15 ou 0.16).

Mes codes

rghk

rghk permet de définir des raccoucrcis clavier globaux (actifs même si l’applications est en arrière plan).
Le code suivant permet d’afficher Binded lorsque les touches control et a sont enfoncées. Un exemple plus détaillé est disponible avec le code source.

La dernière version de rghk, pas encore disponible sous debian, apporte des changements importants :
l’appel à require a été modifié,
la possibilité d’obtenir la « valeur d’une touche clavier » depuis une chaîne de caractère.

ZiK

Si vous voulez tester le lecteur audio nommé ZiK, un paquet debian est disponible. Les instructions pour l’installation du paquet sont disponibles sur le wiki.
Pour les utilisateurs d’Ubuntu un ppa permet une installation aisée de ZiK sous ubuntu. L’installation est détaillée sur le wiki.
N’hésitez pas à faire part de vos impressions.

ZiK utilise intensivement le thème de l’utilisateur. Seules quelques images sont fournies directement par le lecteur audio.
J’aimerai personnaliser ces dernières. Cependant, je n’ai pas le talent nécessaire pour créer ces images. Je lance donc un appel à contribution.

Pour l’instant six images sont concernées. On peut les apercevoir au niveau du bouton qui permet de changer de vue. Il faudrait donc des images représentant :
la vue navigateur,
la vue liste de lecture,
la vue générale (navigateur et liste de lecture),
la vue compacte (navigateur et liste de lecture cachés),
la vue cd,
la vue radio.

Par la suite, trois autres images devraient être nécessaires. Elles représenteront :
un dossier,
un fichier audio,
une liste de lecture (fichiers m3u, pls ou xspf…).
Elles seront visibles depuis la partie navigateur.

J’aimerai que les images soient au format svg et sous une licence (Creative Commons ?) permettant leur distribution avec les sources de ZiK ainsi qu’une intégration facile à des distributions linux (ex : debian).

N’hésitez pas à me contacter si vous avez des questions où si vous êtes intéressés pour contribuer à ZiK.
Je remercie d’avance toute personne me contactant à ce sujet.