|
1 # Architecture générale du Metadataplayer # |
|
2 |
|
3 ATTENTION ! |
|
4 Cette documentation se réfère à la v.3 du Metadataplayer, actuellement disponible dans la branche **new-model** du repository |
|
5 http://www.iri.centrepompidou.fr/dev/hg/metadataplayer |
|
6 |
|
7 ## Bibliothèques extérieures ## |
|
8 |
|
9 Les bibliothèques utilisées par le Metadataplayer sont regroupées dans *src/libs* |
|
10 |
|
11 ### LAB.js ### |
|
12 |
|
13 - **Fichier**: LAB.min.js |
|
14 - **Licence**: MIT. |
|
15 - **Rôle**: Charge les autres bibliothèques extérieures et les widgets. |
|
16 - **Utilisé par**: Code principal. |
|
17 - Du fait de ce mode de chargement, il s’agit de la seule bibliothèque nécessaire au moment de l’initialisation du code. |
|
18 - **Site**: http://labjs.com/ |
|
19 |
|
20 ### jQuery ### |
|
21 |
|
22 - **Fichier**: jquery.min.js |
|
23 - **Licence**: Double, MIT et GPL. |
|
24 - **Rôle**: Gère les actions du code sur la structure du document HTML (DOM) |
|
25 - **Utilisé par**: Code principal et tous les widgets. |
|
26 - **Site**: http://jquery.org/ |
|
27 |
|
28 ### jQuery UI ### |
|
29 |
|
30 - **Fichiers**: jquery-ui.min.js et jquery-ui.css |
|
31 - **Licence**: Double, MIT et GPL. |
|
32 - **Rôle**: Fournit des éléments d’interface utilisateurs, tels que *Sliders* |
|
33 - **Utilisé par**: Widgets, Controller (pour le volume) et Slider (pour le *Slider de progression*) |
|
34 - **Site**: http://jqueryui.com/ |
|
35 |
|
36 ### Underscore ### |
|
37 |
|
38 - **Fichier**: underscore-min.js |
|
39 - **Licence**: MIT. |
|
40 - **Rôle**: Fournit des fonctionnalités orientées programmation fonctionnelle pour manipuler tableaux, objets et fonctions. |
|
41 - **Utilisé par**: Code principal et widgets. |
|
42 - **Site**: http://documentcloud.github.com/underscore/ |
|
43 |
|
44 ### Popcorn ### |
|
45 |
|
46 - **Fichier**: popcorn-complete.min.js |
|
47 - **Licence**: MIT. |
|
48 - **Rôle**: Fournit une gestion de la lecture de vidéos HTML5. |
|
49 - **Utilisé par**: Players HTML5 et Youtube, ainsi que pour la communication avec le reste du Metadataplayer lorsque l’un de ces players est utilisé. |
|
50 - **Site**: http://popcornjs.org/ |
|
51 |
|
52 ### Mustache ### |
|
53 |
|
54 - **Fichier**: mustache.js |
|
55 - **Licence**: MIT. |
|
56 - **Rôle**: Permet de remplir des gabarits (*templates*) HTML. |
|
57 - **Utilisé par**: widgets. |
|
58 - **Site**: http://mustache.github.com/ |
|
59 |
|
60 ### Raphael ### |
|
61 |
|
62 - **Fichier**: raphael-min.js |
|
63 - **Licence**: MIT. |
|
64 - **Rôle**: Fournit une interface de dessin vectoriel (utilise SVG ou VML selon les navigateurs) |
|
65 - **Utilisé par**: Widgets et Sparkline |
|
66 - **Site**: http://raphaeljs.com/ |
|
67 |
|
68 ### ktbs4js Tracemanager ### |
|
69 |
|
70 - **Fichier**: tracemanager.js |
|
71 - **Licence**: LGPL. |
|
72 - **Rôle**: Permet de s’interfacer avec le système de gestion de traces KTBS, créé par Olivier Aubert (Liris) |
|
73 - **Utilisé par**: TraceWidget |
|
74 - **Site**: http://github.com/oaubert/ktbs4js |
|
75 |
|
76 ## Code principal (core) du Metadataplayer ## |
|
77 |
|
78 Dans la version *release* du metadataplayer, les fichiers Javascript et CSS sont répartis entre le *core* et les *widgets*. |
|
79 |
|
80 *LdtPlayer-core.js* est compilé à partir de plusieurs fichiers Javascript situés (sauf LAB.min.js) dans *src/js*: |
|
81 |
|
82 ### header.js ### |
|
83 |
|
84 Contient les crédits du Metadataplayer, ainsi que les informations sur la licence (*CeCILL-C*) |
|
85 |
|
86 ### LAB.js ### |
|
87 |
|
88 cf. Bibliothèques extérieures. |
|
89 |
|
90 ### init.js ### |
|
91 |
|
92 Définit l’objet *IriSP*, qui sert d’espace de nommage pour tout le Metadataplayer. |
|
93 Contient la classe *IriSP.Metadataplayer*, dont l’instanciation est la porte d’entrée principale du code. |
|
94 |
|
95 ### pop.js ### |
|
96 |
|
97 Contient *IriSP.PopcornReplacement*, c’est à dire une version simplifiée de Popcorn pour communiquer avec des lecteurs vidéos non-supportés par Popcorn. |
|
98 Au moment de la création de cette partie, l’interfaçage Popcorn-jwplayer n’était pas satisfaisant, à remplacer éventuellement par de vrais players/plugins pour Popcorn. |
|
99 |
|
100 ### utils.js ### |
|
101 |
|
102 Contient quelques fonctions utilitaires, telles que *IriSP.loadCss*, qui est l’équivalent pour les fichiers CSS de LAB.js. |
|
103 |
|
104 ### model.js ### |
|
105 |
|
106 Contient les classes de gestion du modèle de données Cinelab, regroupées sous l’espace de nommage *IriSP.Model*. |
|
107 |
|
108 ### widgets.js ### |
|
109 |
|
110 Contient la classe de base *IriSP.Widgets.Widget*, qui fournit les fonctionnalités de base pour les widgets. |
|
111 |
|
112 ### players ### |
|
113 |
|
114 Les fichiers de ce répertoire permettent d’interfacer le *Popcorn Replacement* (cf. *pop.js*) avec des lecteurs vidéo tiers. |
|
115 |
|
116 Existent actuellement: |
|
117 |
|
118 1. **player.jwplayer**, pour communiquer avec JwPlayer, utilisé pour lire des flux RTMP sur la plateforme *Ligne de temps* |
|
119 2. **player.dailymotion**, pour lire des vidéos du *Youtube à la française* |
|
120 3. **player.allocine**, pour le player de allocine.net |
|
121 4. **player.mashup**, pour le player de bout à bout Flash créé par Thibaut Cavalié. |
|
122 |
|
123 ### serializers ### |
|
124 |
|
125 Les Sérialiseurs servent d’interface entre les formats de données utilisés pour les échanges avec les serveurs. |
|
126 |
|
127 Deux sérialiseurs existent à l’heure actuelle: |
|
128 |
|
129 1. **PlatformSerializer**, pour lire les flux JSON fournis par la plateforme *Lignes de Temps*. |
|
130 2. **PlatformAnnotateSerializer**, pour communiquer avec l’API d’ajout d’annotations de la plateforme, dont le format est légèrement différent. |
|
131 |
|
132 ## Widgets ## |
|
133 |
|
134 Les Widgets sont des modules, visibles ou non, permettant de rajouter des fonctionnalités au Metadataplayer. |
|
135 |
|
136 Situés dans le répertoire *src/widgets*, ils contiennent nécessairement un fichier de code *NomDuWidget.js* et, optionnellement un fichier de style *NomDuWidget.css* |
|
137 |
|
138 #### Options courantes #### |
|
139 |
|
140 - Les widgets affichant des annotations possèdent l’option *annotation\_type*, qui peut prendre les valeurs suivantes: |
|
141 - Chaîne de caractères: prend en compte les types d’annotations dont le titre contient la chaîne. Exemple: "chap" permet notamment d’afficher les annotations dans le type d’annotation "Chapitrage" |
|
142 - Tableau de chaînes: pour prendre en compte plusieurs types d’annotations |
|
143 - false: pour prendre en compte toutes les annotations du projet |
|
144 - *requires*, qui permet d’encapsuler un widget dans un autre. |
|
145 |
|
146 Voici la liste des widgets actuellement disponibles, avec leurs options: |
|
147 |
|
148 ### HelloWorld ### |
|
149 |
|
150 - **Rôle**: Widget d’exemple démontrant l’API de création de widgets |
|
151 - **Options**: |
|
152 - **text**: (défaut: "world"), texte à afficher après "Hello, " |
|
153 - Utilise un fichier CSS: oui |
|
154 |
|
155 ### Slider ### |
|
156 |
|
157 - **Rôle**: Barre de progression et *Slider* indiquant la position de la tête de lecture vidéo et permettant de la déplacer. |
|
158 - **Options**: |
|
159 - **minimized\_height**: (défaut: 4), hauteur en pixels du *Slider* en mode minimisé |
|
160 - **maximized\_height**: (défaut: 10), hauteur en pixels du *Slider* en mode maximisé (lorsque la souris passe dessus) |
|
161 - **minimize\_timeout**: (défaut: 1500), durée en millisecondes avant que le *Slider* ne se minimise. À une valeur de 0, le *Slider* ne se minimise plus. |
|
162 - Utilise la bibliothèque: jQuery UI |
|
163 - Utilise un fichier CSS: oui |
|
164 |
|
165 ### Controller ### |
|
166 |
|
167 - **Rôle**: Boutons Lecture/Pause, Rechercher, Ouvrir l’annotateur et contrôle du volume |
|
168 - **Options**: |
|
169 - **disable\_annotate\_btn**: (défaut: false), permet de désactiver le bouton d’ouverture de l’annotateur s’il est à *true* |
|
170 - **disable\_search\_btn**: (défaut: true), permet de désactiver le bouton de recherche d’annotations |
|
171 - Utilise la bibliothèque: jQuery UI |
|
172 - Utilise un fichier CSS: oui |
|
173 |
|
174 ### Arrow ### |
|
175 |
|
176 - **Rôle**: Dessine la flèche indiquant la position de l’annotation |
|
177 - **Options**: |
|
178 - **arrow\_height**: (défaut: 16), hauteur en pixels de la flèche |
|
179 - **arrow\_width**: (défaut: 24), largeur en pixels de la flèche |
|
180 - **base\_height**: (défaut: 0), hauteur entre le bas de la flèche et le bas du widget. Nécessaire si l’on souhaite faire un widget aux bords arrondis. |
|
181 - **base\_curve**: (défaut: 0), rayon de courbure des bords arrondis du widget. |
|
182 - **fill\_url**: URL d’une image de remplissage pour le widget |
|
183 - **fill\_color**: (défaut: "#ffffff" = blanc), couleur de remplissage du widget. Peut-être remplacé par un dégradé sous la forme angle en degrés-couleur de début-couleur de fin, ex: "90-#000-#fff" |
|
184 - **stroke\_color**: (défaut: "#b7b7b7" = gris), couleur de la bordure du widget. |
|
185 - **stroke\_width**: (défaut: 1.5), épaisseur en pixels de la bordure du widget. |
|
186 - **animation\_speed**: (défaut: 20), vitesse de déplacement de la flèche. |
|
187 - **pilot\_widget**: (défaut: "Annotation"), widget commandant la position de la flèche. |
|
188 - Utilise la bibliothèque: Raphael |
|
189 - Utilise un fichier CSS: non |
|
190 |
|
191 ### Annotation ### |
|
192 |
|
193 - **Rôle**: Affiche les informations relatives à une annotation au moment où celle-ci est jouée |
|
194 - **Options**: |
|
195 - **annotation\_type**: (défaut: "chapitrage"), cf. *Options courantes*, plus haut. |
|
196 - **show\_top\_border**: (défaut: false), afficher ou non la bordure en haut du widget (au cas où il est utilisé sans/avec le widget *Arrow*) |
|
197 - **site\_name**: "Lignes de Temps", nom du site à afficher lorsque l’on clique sur les boutons de partage pour réseaux sociaux. |
|
198 - Utilise un fichier CSS: oui |
|
199 |
|
200 ### CreateAnnotation ### |
|
201 |
|
202 - **Rôle**: Permet de créer une annotation en affichant un formulaire |
|
203 - **Options**: |
|
204 - **show\_title\_field**: (défaut: true), affiche un champ permettant de saisir le titre de l’annotation. |
|
205 - **creator\_name**: nom d’utilisateur du créateur de l’annotation. |
|
206 - **creator\_avatar**: URL de l’image de profil du créateur de l’annotation. |
|
207 - **tags**: (défaut: false), liste des tags à afficher, sous la forme d’un tableau d’objets type [ { id: "tag-001", title: "" } ]. Si la valeur est false, affiche les tags les plus utilisés du projet. |
|
208 - **max\_tags**: (défaut: 8), nombre de tags à afficher. |
|
209 - **polemics**: boutons polémiques à afficher, sous la forme d’un tableau d’objets indiquant mot-clé à ajouter, couleur du fond du bouton, couleur du bouton, ex: [ { keyword: "++", background\_color: "#00a000", text\_color: "#ffffff" } ] |
|
210 - **annotation\_type**: (défaut: "Contributions"), cf. *Options courantes*, plus haut. |
|
211 - **api\_serializer**: (défaut: "ldt\_annotate"), sérialiseur à utiliser pour l’envoi des annotations. |
|
212 - **api\_endpoint\_template**: URL de l’API, où {{id\}\} est remplacé par l’ID du projet, ex: "http://ldt.iri.centrepompidou.fr/ldtplatform/api/ldt/annotations/{{id}}.json". |
|
213 - **api\_method**: (défaut: "PUT"), méthode HTTP utilisée pour envoyer les annotations. La plateforme *Lignes de temps* utilise PUT, mais cette méthode devrait être réservée pour la création d’une ressource dont l’URL est connue à l’avance. |
|
214 - **close\_widget\_timeout**: (défaut: 0), durée en millisecondes avant que le widget ne soit refermé après l’envoi d’une annotation. Si la valeur est 0, le widget ne se referme pas. |
|
215 - Utilise un fichier CSS: oui |
|
216 |
|
217 ### Polemic ### |
|
218 |
|
219 - **Rôle**: Affiche la *timeline polémique*, c’est à dire les tweets colorés en fonction de la syntaxe polémique. Selon le volume de tweets, deux modes de représentation existent: |
|
220 - Avec un faible volume, les tweets sont des carrés dessinés individuellement. |
|
221 - Avec un volume élevé, les colonnes présentent les volumes agrégés de tweets par couleur. |
|
222 - **Options**: |
|
223 - **element\_width**: (défaut: 5), largeur en pixels d’une tranche de tweets. |
|
224 - **element\_height**: (défaut: 5), hauteur en pixels d’un tweet, en mode faible volume. |
|
225 - **max\_elements**: (défaut: 15), nombre de tweets dans une colonne à partir duquel le mode de représentation change. |
|
226 - **annotation\_type**: (défaut: "tweet"), cf. *Options courantes*, plus haut. |
|
227 - **defaultcolor**: (défaut: "#585858" = gris), couleur des tweets qui n’ont pas d’annotation polémique. |
|
228 - **foundcolor**: (défaut: "#fc00ff" = mauve), couleur d’affichage des tweets correspondant à un résultat de recherche. |
|
229 - **polemics**: couleurs polémiques à afficher, en fonction d’une recherche de termes, type [ { keywords: [ "++" ], color: "#1D973D" } ] |
|
230 - Utilise un fichier CSS: oui |
|
231 |
|
232 ### Tweet ### |
|
233 |
|
234 - **Rôle**: Affiche furtivement le contenu d’un tweet |
|
235 - **Options**: |
|
236 - **hide_timeout**: (défaut: 5000), durée en millisecondes, avant que l’affichage du Tweet ne se referme |
|
237 - **polemics**: identique au paramètre *polemics* du widget *Polemic* |
|
238 |
|
239 ### Sparkline ### |
|
240 |
|
241 - **Rôle**: Affiche une courbe indiquant l’évolution du volume d’annotations au cours du temps. |
|
242 - **Options**: |
|
243 - **annotation\_type**: cf. *Options courantes*, plus haut. |
|
244 - **lineColor**: (défaut: "#7492b4" = gris-bleu), couleur de la courbe |
|
245 - **fillColor**: (défaut: "#aeaeb8" = gris), couleur de la surface sous la courbe |
|
246 - **lineWidth**: (défaut: 2), épaisseur en pixels de la courbe |
|
247 - **slice\_count**: (défaut: 20), nombre des tranches horaires dans lesquelles les annotations sont réparties pour calculer la courbe |
|
248 - **height**: (défaut: 50), hauteur en pixels de la courbe |
|
249 - **margin**: (défaut: 5), marge en pixels au-dessus de la courbe |
|
250 - Utilise la bibliothèque: Raphael |
|
251 - Utilise un fichier CSS: non |
|
252 |
|
253 ### Tagcloud ### |
|
254 |
|
255 - **Rôle**: Affiche un nuage de mots-clés |
|
256 - **Options**: |
|
257 - **include\_titles**: (défaut: true), utiliser le contenu du champ titre des annotations pour calculer le nuage de mots-clés. |
|
258 - **include\_descriptions**: (défaut: true), utiliser le contenu du champ description des annotations pour calculer le nuage. |
|
259 - **include\_tag\_texts**: (défaut: true), utiliser les textes des tags liés aux annotations pour calculer le nuage de mots-clés. |
|
260 - **tag\_count**: (défaut: 30), nombre maximum de mots-clés à afficher. |
|
261 - **stopword\_language**: (défaut: "fr"), code de langue correspondant à une liste de mots vides à exclure du nuage. |
|
262 - **custom\_stopwords**: (défaut: []), liste de mots-vides à exclure du nuage. |
|
263 - **exclude\_pattern**: (défaut: false), expression régulière à exclure du nuage. |
|
264 - **annotation\_type**: (défaut: false), cf. *Options courantes*, plus haut. Concerne les annotations dont les contenus sont utilisés pour calculer le nuage. |
|
265 - **segment\_annotation\_type**: (défaut: false), permet de définir la segmentation du nuage de mots-clés et de calculer un nuage pour chaque segment du type d’annotation choisi. Lorsque ce paramètre est à *false*, un seul nuage est calculé pour toute la durée de la vidéo. |
|
266 - **min\_font\_size**: (défaut: 10), taille de caractères (en pixels) pour le mot le moins fréquent. |
|
267 - **max\_font\_size**: (défaut: 26), taille de caractères (en pixels) pour le mot le plus fréquent. |
|
268 - Utilise un fichier CSS: oui |
|
269 |
|
270 ### AnnotationsList ### |
|
271 |
|
272 - **Rôle**: Affiche une liste d’annotations |
|
273 - **Options**: |
|
274 - **ajax\_url**: (défaut: false), spécifie un gabarit d’URL lorsque les annotations doivent être chargées par une API spécifique (API de segment). Dans l’URL, {{media}} sera remplacé par l’ID du média, {{begin}} par le *timecode* de début en millisecondes, {{end}} par le *timecode* de fin en millisecondes. Si le réglage est à *false*, les annotations affichées seront celles chargées à l’initialisation du Widget. Sur la plateforme *Lignes de Temps*, cette URL est http://ldt.iri.centrepompidou.fr/ldtplatform/api/ldt/segments/{{media}}/{{begin}}/{{end}}?callback=? |
|
275 - **ajax\_granularity**: (défaut: 300000 ms = 5 minutes), spécifie la durée qui doit être chargée par l’API de segment, de part et d’autre du timecode courant (cf. ci-dessus) |
|
276 - **default\_thumbnail**: imagette à afficher par défaut à côté d’une annotation lorsque l’annotation n’a pas d’imagette. |
|
277 - **foreign\_url**: spécifie un gabarit d’URL lorsque l’annotation n’a pas d’information d’URL et que l’annotation est dans un autre projet. Dans l’URL, {{media}} sera remplacé par l’ID du média, {{project}} par l’ID du projet, {{annotationType}} par l’ID du type d’annotation, {{annotation}} par l’ID de l’annotation. Sur la plateforme *Lignes de temps*, cette URL est http://ldt.iri.centrepompidou.fr/ldtplatform/ldt/front/player/{{media}}/{{project}}/{{annotationType}}#id={{annotation}} |
|
278 - **annotation\_type**: (défaut: false), cf. *Options courantes*, plus haut. |
|
279 - **refresh\_interval**: (défaut: 0), intervalle auquel le widget recharge en Ajax la liste des annotations (que l’on utilise l’API de segment ou non) |
|
280 - **limit\_count**: (défaut: 10), nombre maximum d’annotations à afficher simultanément. |
|
281 - **newest\_first**: (défaut: false), *true*: classe les annotations par ordre antéchronologique de création, *false*: classe les annotations par ordre chronologique de leur timecode vidéo. |
|
282 - Utilise un fichier CSS: oui |
|
283 |
|
284 ### Media ### |
|
285 |
|
286 - **Rôle**: Affiche le média en cours, ainsi que la liste des autres médias du projet. Utilisé principalement pour les mashups |
|
287 - **Options**: |
|
288 - **default\_thumbnail**: imagette à afficher par défaut à côté d’un média lorsque le média n’a pas d’imagette. |
|
289 - **media\_url\_template**: spécifie un gabarit d’URL lorsque le média n’a pas d’information d’URL, par exemple: "http://ldt.iri.centrepompidou.fr/ldtplatform/ldt/front/player/{{media}}/" |
|
290 - Utilise un fichier CSS: oui |
|
291 |
|
292 ### Tooltip ### |
|
293 |
|
294 - **Rôle**: Affiche une infobulle, utilisé uniquement comme *widget inclus* dans d’autres widgets. |
|
295 - Pas d’options |
|
296 - Utilise un fichier CSS: oui |
|
297 |
|
298 ### Trace ### |
|
299 |
|
300 - **Rôle**: Envoi des traces au serveur KTBS |
|
301 - **Options**: |
|
302 - **js\_console**: (défaut: false), écriture ou non des traces dans la console du navigateur. |
|
303 - **url**: (défaut: "http://traces.advene.org:5000/"), URL du serveur de traces |
|
304 - **requestmode**: (défaut: "GET"), méthode HTTP utilisée pour l’envoi des traces (seul *"GET"* permet le *cross-domain*). |
|
305 - **syncmode**: (défaut: "sync"), envois groupés (mode *"delayed"*) ou non (*"sync"*) des traces |
|
306 - Utilise la bibliothèque: ktbs4js tracemanager |
|
307 - Utilise un fichier CSS: non |
|
308 |
|
309 ### Mediafragment ### |
|
310 |
|
311 - **Rôle**: Gère les URLs à la norme *Mediafragment*: change la position de la tête de lecture en fonction de l’URL et inversement. |
|
312 - Une URL finissant par #id=*id de l’annotation* pointe sur une annotation, par #t=*temps en secondes* vers un timecode de la vidéo. |
|
313 - Pas d’options |
|
314 - Utilise un fichier CSS: non |