Hello,
depuis peu, les modifications évoquées dans le billet précédent ont été réalisées. L’API a été modifiée pour toutes les fonctions qui permettent d’effectuer des sélections sur la base de donnée. Ce blog étant aussi en quelque sorte un carnet de laboratoire, je vais donc y expliquer le fonctionnement de ces fonctions ainsi que la manière de les utiliser. A terme, ces informations figureront directement dans la documentation (en anglais) de libvalhalla. Il est judicieux de consulter la documentation Doxygen déjà présente dans l’en-tête public (valhalla.h) qui peut être généré via un paramètre du script "configure".
Cet article est long et très spécifique à libvalhalla du côté développeur uniquement. Si vous êtes un simple utilisateur d’Enna, vous ne verrez pas vraiment de différence par rapport à avant car les modifications sont majoritairement internes.
Il y a trois fonctions publiques et chacune est complémentaire aux autres.
int valhalla_db_metalist_get (
valhalla_t *handle,
valhalla_db_item_t *search,
valhalla_db_restrict_t *restriction,
int (*result_cb) (void *data,
valhalla_db_metares_t *res),
void *data);
int valhalla_db_filelist_get (
valhalla_t *handle,
valhalla_file_type_t filetype,
valhalla_db_restrict_t *restriction,
int (*result_cb) (void *data,
valhalla_db_fileres_t *res),
void *data);
int valhalla_db_file_get (
valhalla_t *handle,
int64_t id, const char *path,
valhalla_db_restrict_t *restriction,
valhalla_db_filemeta_t **res);
valhalla_db_metalist_get
Utilisation simple
Elle permet de récupérer une liste de metadata. Cela veut dire, par exemple une liste d’albums, d’auteurs, d’artistes, de genres; peu importe le nom, vous pouvez récupérer n’importe quelle liste. Le résultat se présente toujours sous la forme du nom du champ (comme "author") avec une valeur et un groupe. Sous la forme d’un tableau, cela donnerait quelque chose comme:
| meta id |
meta name |
data id |
data value |
group |
| 2 |
author |
1665 |
Dido |
ENTITIES |
| 2 |
author |
456 |
Ennio Morricone |
ENTITIES |
| 2 |
author |
1257 |
John Williams |
ENTITIES |
| 2 |
author |
1224 |
Linkin Park |
ENTITIES |
Dans cet exemple, uniquement les auteurs sont présents, mais il est également possible de demander une liste de metadata selon un groupe et non selon un nom de meta ou un id. Vous pouvez typiquement demander la liste de toutes les metadata qui appartiennent au group ENTITIES. De ce fait, vous trouverez la liste de tous les auteurs, artistes, compositeurs, studios, etc,…
Sans rentrer encore dans les détails du code, une telle liste se récupère de cette manière:
valhalla_db_item_t s = VALHALLA_DB_SEARCH_TEXT ("author", ENTITIES);
valhalla_db_metalist_get (handle, &s, NULL, callback, NULL);
Et sans expliquer en détail la fonction, l’argument "handle" correspond au pointeur sur votre instance de valhalla, "s" (pour search) défini ce que vous cherchez, le troisième argument permet de spécifier des restrictions (qui sont expliquées dans le chapitre suivant), le callback est la fonction dans laquelle chaque ligne du résultat est envoyée et le dernier argument est un pointeur void qui peut être récupéré dans le callback.
Les macros VALHALLA_DB_SEARCH_XXX sont présentes pour simplifier l’utilisation de libvalhalla. Elles ne sont pas indispensables. En réalité, elle ne font qu’attribuer les valeurs au bon endroit dans la structure valhalla_db_item_t. Actuellement il existe trois macros différentes:
VALHALLA_DB_SEARCH_ID(meta_id, group)
VALHALLA_DB_SEARCH_TEXT(meta_text, group)
VALHALLA_DB_SEARCH_GRP(group)
Vous pouvez donc chercher une liste de meta en fonction de l’id, du texte, ou alors vous pouvez récupérer plusieurs noms de metadata différents dans le cas d’une recherche selon un groupe.
Utilisation étendue
Récupérer une liste comme expliqué dans le chapitre précédent est la fonctionnalité la plus simple offerte par cette fonction. Il va de soit qu’il faut pouvoir donner quelques restrictions sur la liste retournée. Il est courant de ne pas vouloir une liste complète. Un exemple parlant concerne la metadata "album". Il est intéressant de pouvoir récupérer tous les albums d’un auteur en particulier. Et c’est ici qu’interviennent les restrictions. Elles permettent d’inclure ou d’exclure certains résultats. D’un point de vue SQL, se sont des sous-requêtes qui limitent les résultats à leur ensemble, ou alors à tous les résultats différents de leur ensemble.
Voici un premier exemple. Vous voulez tous les albums de Dido:
valhalla_db_item_t s = VALHALLA_DB_SEARCH_TEXT ("album", TITLES);
valhalla_db_restrict_t r1 = VALHALLA_DB_RESTRICT_STR (IN, "author", "Dido");
valhalla_db_metalist_get (handle, &s, &r1, callback, NULL);
Le résultat sera un tableau de la même forme que vue précédemment, mais qui contiendra uniquement les albums de Dido.
| meta id |
meta name |
data id |
data value |
group |
| 3 |
album |
1666 |
Life For Rent |
TITLES |
| 3 |
album |
1669 |
No Angel |
TITLES |
| 3 |
album |
1725 |
Safe Trip Home |
TITLES |
Cette requête est déjà bien plus sophistiquée, car vous pouvez imaginer de donner ce genre de restriction pour n’importe quel metadata. Un autre exemple, vous pourriez lister tous les albums d’une certaine année. Il n’y a aucune limite sur les choix des restrictions. Mais ceci n’est pas suffisant, et il y a donc des possibilités un peu plus complexes afin d’avoir des résultats plus spécifiques.
Tout d’abord, dans l’exemple précédent, la macro VALHALLA_DB_RESTRICT est utilisée avec un premier argument "IN". Il est possible d’inverser la logique en y inscrivant "NOTIN" à la place. Le résultat deviendrait alors la liste de tous les albums qui existent dans la base de donnée, sauf ceux de Dido.
Utilisation avancée
L’utilisation étendue permet déjà d’effectuer de nombreuse recherches intéressantes. Néanmoins pour les cas les plus précis, elle ne suffit pas. Il est nécessaire parfois de cumuler les restrictions pour affiner le résultats, ou tout simplement, pour avoir des résultats un peu plus exotiques. Ainsi les restrictions sont des listes chaînées, et il est possible de les lier très facilement. Commençons par un exemple, nous désirons la liste de tous les albums de Dido qui ne sont pas de 2003.
valhalla_db_item_t s = VALHALLA_DB_SEARCH_TEXT ("album", TITLES);
valhalla_db_restrict_t r1 = VALHALLA_DB_RESTRICT_STR (IN, "author", "Dido");
valhalla_db_restrict_t r2 = VALHALLA_DB_RESTRICT_STR (NOTIN, "year", "2003");
VALHALLA_DB_RESTRICT_LINK (r2, r1);
valhalla_db_metalist_get (handle, &s, &r1, callback, NULL);
Une nouvelle macro est donc introduite. Elle permet de lier très simplement les restrictions ensemble. La macro doit être comprise de cette manière. "link from r2 to r1", soit lier de r2 à r1. Ainsi c’est r1 qui doit être spécifié dans la fonction valhalla_db_metalist_get(). Il n’y a aucune limite sur le nombre de liens possibles (mise à part qu’une requête ne doit pas dépasser 4096 caractères), néanmoins il ne faut pas tenter de lier toutes les restrictions sur la même car seul le dernier lien sera considéré. Avec trois restrictions, la bonne manière de procéder est donc:
valhalla_db_item_t s = VALHALLA_DB_SEARCH_TEXT ("album", TITLES);
valhalla_db_restrict_t r1 = VALHALLA_DB_RESTRICT_STR (IN, "author", "Linkin Park");
valhalla_db_restrict_t r2 = VALHALLA_DB_RESTRICT_STR (NOTIN, "year", "2003");
valhalla_db_restrict_t r3 = VALHALLA_DB_RESTRICT_STR (NOTIN, "genre", "Alternative");
VALHALLA_DB_RESTRICT_LINK (r3, r2);
VALHALLA_DB_RESTRICT_LINK (r2, r1);
valhalla_db_metalist_get (handle, &s, &r1, callback, NULL);
Ici, la liste concernera donc tous les albums de Linkin Park, qui ne sont pas de 2003 et qui ne sont pas du rock/metal alternatif. Okay, la liste ne risque pas d’être bien longue avec cet exemple :-P, mais ce qui compte c’est de montrer le principe. Les restrictions sont liées de la manière suivante: de r3 à r2 et de r2 à r1. En code ça donnerait donc:
r2.next = &r3;
r1.next = &r2;
Le code ci-dessus peut très bien remplacer la macro si vous préférez.
Il y a encore une macro que je n’ai pas vraiment présenté. Pour l’argument de recherche de la fonction, il est possible d’indiquer uniquement un groupe (comme je l’ai mentionné plus haut dans ce billet). Si le groupe est mit à NIL, il y aura toutes les metadata qui seront listées, autrement il n’y aura que les metadata liées au groupe.
Un dernier exemple qui retourne absolument toutes les metadata liées à Dido pour son album Life For Rent.
valhalla_db_item_t s = VALHALLA_DB_SEARCH_GRP (NIL);
valhalla_db_restrict_t r1 = VALHALLA_DB_RESTRICT_STR (IN, "author", "Dido");
valhalla_db_restrict_t r2 = VALHALLA_DB_RESTRICT_STR (IN, "album", "Life For Rent");
VALHALLA_DB_RESTRICT_LINK (r2, r1);
valhalla_db_metalist_get (handle, &s, &r1, callback, NULL);
| meta id |
meta name |
data id |
data value |
group |
| 6 |
track |
19 |
1 |
ORGANIZATIONAL |
| 6 |
track |
225 |
10 |
ORGANIZATIONAL |
| 6 |
track |
229 |
11 |
ORGANIZATIONAL |
| 6 |
track |
242 |
12 |
ORGANIZATIONAL |
| 6 |
track |
92 |
2 |
ORGANIZATIONAL |
| 5 |
year |
50 |
2003 |
TEMPORAL |
| 6 |
track |
202 |
3 |
ORGANIZATIONAL |
| 6 |
track |
101 |
4 |
ORGANIZATIONAL |
| 6 |
track |
223 |
5 |
ORGANIZATIONAL |
| 6 |
track |
96 |
6 |
ORGANIZATIONAL |
| 6 |
track |
231 |
7 |
ORGANIZATIONAL |
| 6 |
track |
196 |
8 |
ORGANIZATIONAL |
| 6 |
track |
187 |
9 |
ORGANIZATIONAL |
| 1 |
title |
1673 |
BonusTrack |
TITLES |
| 2 |
author |
1665 |
Dido |
ENTITIES |
| 1 |
title |
1668 |
Do You Have A Little Time |
TITLES |
| 1 |
title |
1672 |
Dont Leave Home |
TITLES |
| 1 |
title |
1666 |
Life For Rent |
TITLES |
| 3 |
album |
1666 |
Life For Rent |
TITLES |
| 1 |
title |
1678 |
Marys In India |
TITLES |
| 4 |
genre |
104 |
Pop |
CLASSIFICATION |
| 1 |
title |
1670 |
Sand In My Shoes |
TITLES |
| 1 |
title |
1669 |
See The Sun |
TITLES |
| 1 |
title |
1674 |
See You When Youre 40 |
TITLES |
| 1 |
title |
1675 |
Stoned |
TITLES |
| 1 |
title |
1671 |
This Land Is Mine |
TITLES |
| 1 |
title |
1664 |
White Flag |
TITLES |
| 1 |
title |
1667 |
Who Makes You Feel |
TITLES |
Et d’un point de vue SQL
La requête SQL qui effectue les sélections est créée en fonction des arguments de la fonction. Elle se construit comme des lego qui s’imbriquent les uns dans les autres. D’une manière général, sa forme est:
SELECT meta.meta_id, data.data_id, meta.meta_name, data.data_value
FROM (
data INNER JOIN assoc_file_metadata AS assoc
ON data.data_id = assoc.data_id
) INNER JOIN meta
ON assoc.meta_id = meta.meta_id
-- Les conditions sont optionnelles
WHERE
-- Une sous-requête apparait par le biais des restrictions.
-- Il y a autant de sous-requêtes que de restrictions du type IN, NOT IN.
assoc.file_id <IN|NOT IN> (
SELECT assoc.file_id
FROM (
data INNER JOIN assoc_file_metadata AS assoc
ON data.data_id = assoc.data_id
) INNER JOIN meta
ON assoc.meta_id = meta.meta_id
-- A choix, il peut y avoir un ID ou du texte.
WHERE meta.<meta_id|meta_name> = <ID|"TEXT"> AND data.<data_id|data_value> = <ID|"TEXT">
)
-- L'argument search indique quel meta et/ou quel groupe doit être listé
AND meta.<meta_id|meta_name> = <ID|"TEXT">
AND assoc._grp_id = <ID>
GROUP BY assoc.meta_id, assoc.data_id
ORDER BY data.data_value;
Sa longueur varie fortement selon le nombre de conditions. Il est possible de visualiser les requêtes générées par Valhalla en utilisant la verbosité maximale de la bibliothèque.
valhalla_db_filelist_get
Utilisation simple
La récupération d’une liste de fichiers ressemble à celle pour les metadata. La différence vient principalement du deuxième argument qui fait référence au type de fichier (audio, video, etc, …). Ce qui limite ensuite la liste se sont les restrictions. L’utilisation étant exactement la même, je vais aller droit au but avec des exemples.
Pour lister la totalité des fichiers référencés dans la base de donnée, rien de plus simple:
valhalla_db_filelist_get (handle, VALHALLA_FILE_TYPE_NULL, NULL, callback, NULL);
Le fait d’indiquer un type de fichier NULL, permet d’ignorer le type. Le résultat de cette requête correspond à un tableau de ce genre qui contiendrait la totalité de l’arborescence:
| id |
path |
filetype |
| … |
… |
… |
| 101 |
/home/foo/bar/dido/life_for_rent/sand_in_my_shoes.m4a |
AUDIO |
| 102 |
/home/foo/bar/dido/life_for_rent/white_flag.m4a |
AUDIO |
| 103 |
/home/foo/bar/dido/life_for_rent/who_makes_you_feel.m4a |
AUDIO |
| … |
… |
… |
Avec les restrictions
Il est ensuite facile de faire du tri avec les restrictions, de la même manière que pour la fonction précédente. Par exemple, pour lister tous les fichiers d’Ennio Morricone qui ne sont référencés dans aucun album.
valhalla_db_restrict_t r1 = VALHALLA_DB_RESTRICT_STR (IN, "author", "Ennio Morricone");
valhalla_db_restrict_t r2 = VALHALLA_DB_RESTRICT_STR (NOTIN, "album", NULL);
VALHALLA_DB_RESTRICT_LINK (r2, r1);
valhalla_db_filelist_get (handle, VALHALLA_FILE_TYPE_NULL, &r1, callback, NULL);
Et ci-dessous, un autre exemple qui correspond à la catégorie "Non Classé" dans Enna. Tous les fichiers qui ne sont ni dans un album, ni lié à un author et dont le genre est indéfini.
valhalla_db_restrict_t r1 = VALHALLA_DB_RESTRICT_STR (NOTIN, "album", NULL);
valhalla_db_restrict_t r2 = VALHALLA_DB_RESTRICT_STR (NOTIN, "author", NULL);
valhalla_db_restrict_t r3 = VALHALLA_DB_RESTRICT_STR (NOTIN, "genre", NULL);
VALHALLA_DB_RESTRICT_LINK (r3, r2);
VALHALLA_DB_RESTRICT_LINK (r2, r1);
valhalla_db_filelist_get (handle, VALHALLA_FILE_TYPE_NULL, &r1, callback, NULL);
Facile, non?
A noter que ce n’est pas encore totalement optimal, car le groupe ne peut pas être donné avec les restrictions. Ainsi n’importe quel metadata de n’importe quel groupe est considérée dans l’inclusion comme l’exclusion.
Et d’un point de vue SQL
La aussi, la requête ressemble beaucoup à la précédente avec des différences au niveau de ce qui est sélectionné et dans quelle table.
SELECT file_id, file_path, _type_id
FROM file AS assoc
-- Les conditions sont optionnelles
WHERE
-- Une sous-requête apparait par le biais des restrictions.
-- Il y a autant de sous-requêtes que de restrictions du type IN, NOT IN.
assoc.file_id <IN|NOT IN> (
SELECT assoc.file_id
FROM (
data INNER JOIN assoc_file_metadata AS assoc
ON data.data_id = assoc.data_id
) INNER JOIN meta
ON assoc.meta_id = meta.meta_id
-- A choix, il peut y avoir un ID ou du texte.
WHERE meta.<meta_id|meta_name> = <ID|"TEXT"> AND data.<data_id|data_value> = <ID|"TEXT">
)
-- Le type n'est pas inscrit dans la requête si la valeur est NULL.
AND _type_id = <ID>
ORDER BY file_id;
Si dans la clause FROM, la table "file" créer un alias "assoc", c’est uniquement pour une question de factorisation dans le code par rapport à la sous-requête.
valhalla_db_file_get
Maintenant que l’on a vu comment récupérer des listes de metadata ainsi que des listes de fichiers, il est important de pouvoir aussi récupérer des metadata en fonction d’un fichier spécifique. Cette possibilité n’existait pas avec l’ancien modèle car les fichiers étaient toujours retournés dans une liste. Ici il est question d’un seul fichier à la fois. Il faut également être conscient que cette fonction est liée uniquement à la base de donnée, si un fichier non référencé dans la base mais existant quelque part est donné en argument, aucun résultat ne sera retourné (cette possibilité existera quand j’implémenterai le "scan on-demand").
Les arguments sont donc l’id du fichier, le chemin du fichier, des restrictions et le pointeur sur la structure de résultat. Il n’y a pas de callback pour l’utilisateur car le résultat est limité à un seul fichier (en réalité il y a un callback interne qui récupère toutes les metadata car le vrai résultat est sur plusieurs lignes).
Les metadata sont disponibles dans une structure chaînée. Je dois également introduire une nouvelle possibilité des restrictions. Mais tout d’abord, voici un exemple:
valhalla_db_filemeta_t *metadata = NULL;
valhalla_db_restrict_t r1 = VALHALLA_DB_RESTRICT_STR (EQUAL, "track", NULL);
valhalla_db_restrict_t r2 = VALHALLA_DB_RESTRICT_STR (EQUAL, "title", NULL);
VALHALLA_DB_RESTRICT_LINK (r2, r1);
valhalla_db_file_get (handle, 0, "/home/foo/bar/dido/life_for_rent/white_flag.m4a", &r1, &metadata);
/* ... */
VALHALLA_DB_FILEMETA_FREE (metadata);
L’argument EQUAL dans la macro VALHALLA_DB_RESTRICT sert à limiter les résultats à des metadata précises. Sans les restrictions, la structure metadata contiendrait absolument toutes les metadata. Mais dans cet exemple, la structure contient uniquement le track et le titre. A noter qu’utiliser IN ou NOTIN ici ça n’a aucun sens. De même qu’utiliser EQUAL pour les deux fonctions précédentes (voir la conclusion).
Il faut être conscient que plusieurs tracks et plusieurs titres peuvent être retournés pour un même fichier. Car rien n’exclus que certains noms de metadata n’existent pas dans différents groupes. Et comme je l’ai dis plus haut, il n’est pour le moment pas possible de limiter une restriction à un groupe. Néanmoins le groupe est un champ de la structure valhalla_db_filemeta_t, il est donc possible de faire un tri à postériori.
Après utilisation des metadata, il ne faut pas oublier de les libérer avec VALHALLA_DB_FILEMETA_FREE().
Et d’un point de vue SQL
SELECT file.file_id, assoc._grp_id, meta.meta_id, data.data_id, meta.meta_name, data.data_value
FROM ((
file INNER JOIN assoc_file_metadata AS assoc
ON file.file_id = assoc.file_id
) INNER JOIN data
ON data.data_id = assoc.data_id
) INNER JOIN meta
ON assoc.meta_id = meta.meta_id
-- Les conditions sont optionnelles
WHERE
-- Une condition apparait par le biais des restrictions.
-- Il y a autant de conditions que de restrictions du type EQUAL.
-- A choix, il peut y avoir un ID ou du texte. Chaque restriction
-- est séparée par un OR.
(
(meta.<meta_id|meta_name> = <ID|"TEXT"> AND data.<data_id|data_value> = <ID|"TEXT">)
<OR> ...
)
-- Il faut l'id d'un fichier ou un path
AND file.<file_id|file_path> = <ID|"PATH">
;
Cette requête retourne autant de lignes qu’il y a de metadata. Mais pour l’utilisateur, tout est transparent car les résultats sont tous retournés dans une structure chaînée.
En conclusion
Les possibilités de ce nouveau système sont très larges par rapport à l’ancien. Bien qu’il y ait encore quelques manques pour pouvoir spécifier des groupes avec les restrictions, il est possible de retrouver les données avec peu de lignes de code et simplement, tout en ayant des requêtes relativement complexes qui se créer en interne. Il y aura forcément des modifications à l’avenir, je tâcherais de garder à jour cet article.
Et pour en revenir aux restrictions et à l’argument qui peut prendre la valeur IN, NOTIN ou EQUAL, il faut comprendre que c’est avant tout une question de factorisation en interne. IN et NOTIN devraient être utilisés uniquement avec les deux premières fonctions présentées qui récupèrent des listes, et EQUAL devrait être utilisé uniquement pour la récupération des metadata d’un fichier. Je vais continuer à travailler sur ces éléments dans les jours à venir afin d’éviter des confusions.
A bientôt,
Mathieu SCHROETER
WordPress:
J’aime chargement…
Je vous invite à consulter le site internet. DaisyDuck est un lecteur de livre audio Daisy 2.02, basé sur Qt et libVLC. Il est multi-plateforme et distribué aussi bien pour Windows que pour Linux. Il pourrait également être adapté sans trop de problème à MacOSX. Mais pour des questions de temps, je me suis arrêté à la version Windows.
. C’est aussi mauvais qu’avant. Les microsecondes n’apportent absolument rien. Au début je me suis fais avoir car je pensais vraiment que les 25 us étaient atteints. Et bien que la fonction est sensée être plus rapide d’après mes recherches, en pratique (sous Windows XP), il n’y a pas de quoi en faire une montagne. Il a fallut presque le même nombre de lecture (un peu plus de 8000) pour environ 15 ms.
.
Le problème rencontré part Ben et Nico n’était pas reproductible chez moi. Et étant principalement responsable de libplayer depuis toutes les modifications que j’ai apporté, et donc connaissant de fond en comble sa structure et son fonctionnement actuel, il est forcément de mon devoir que de corriger les problèmes connus.
Au pays du dieu Odin, il est temps de ne plus limiter l’entrée de la Valhalla uniquement aux guerriers valeureux. Mais soyons fous et acceptons tout le monde, et peu importe leurs caractéristiques (cf. 
