diff -r 5aadbc9f27cd -r a39ff507b050 doc/architecture.en.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/architecture.en.md Fri Jul 27 19:22:25 2012 +0200 @@ -0,0 +1,331 @@ +# Architecture of Metadataplayer # + +WARNING ! +This documentation refers to version 0.3 of Metadataplayer, now available under the **new-model** branch in our repository +http://www.iri.centrepompidou.fr/dev/hg/metadataplayer + +## External Libraries ## + +External libraries are bundled in the *src/libs* directory + +### LAB.js ### + +- **File**: LAB.min.js +- **License**: MIT. +- **Role**: Loads other librairies and widgets. +- **Used in**: Metadataplayer core. +- As LAB.js is used to load other libraries, it's the only library called before loading the Metadataplayer core. +- **Library homepage**: http://labjs.com/ + +### jQuery ### + +- **File**: jquery.min.js +- **License**: Double, MIT and GPL. +- **Role**: Manages HTML document (DOM) access and Ajax calls. +- **Used in**: Metadataplayer core and all widgets. +- **Library homepage**: http://jquery.org/ + +### jQuery UI ### + +- **Fichiers**: jquery-ui.min.js and jquery-ui.css +- **License**: Double, MIT and GPL. +- **Role**: Manages User Interface elements, such as *Sliders* +- **Used in**: Widgets : Controller (for volume control) et Slider (Time *progress slider*) +- **Library homepage**: http://jqueryui.com/ + +### Underscore ### + +- **File**: underscore-min.js +- **License**: MIT. +- **Role**: Adds functional-programming facilities to handle objects, arrays and functions. +- **Used in**: Metadataplayer core and most widgets. +- **Library homepage**: http://underscorejs.org/ + +### Popcorn ### + +- **File**: popcorn-complete.min.js +- **License**: MIT. +- **Role**: Handles HTML5 Video Playback. +- **Used in**: HTML5 and Youtube video players. Also handles Metadataplayer events when one of these players is used. +- **Library homepage**: http://popcornjs.org/ + +### Mustache ### + +- **File**: mustache.js +- **License**: MIT. +- **Role**: A templating library to generate HTML code. +- **Used in**: widgets. +- **Library homepage**: http://mustache.github.com/ + +### Raphael ### + +- **File**: raphael-min.js +- **License**: MIT. +- **Role**: A vectorial drawing interface (using SVG or VML depending on browsers) +- **Used in**: Arrow and Sparkline widgets +- **Library homepage**: http://raphaeljs.com/ + +### ktbs4js Tracemanager ### + +- **File**: tracemanager.js +- **License**: LGPL. +- **Role**: Interface with the KTBS trace management system, created by Olivier Aubert (Liris) +- **Used in**: Trace widget +- **Library homepage**: http://github.com/oaubert/ktbs4js + +## Metadataplayer core ## + +In Metadataplayer, Javascript and CSS files are divided in *core* and *widgets*. + +In the release (compiled) version, the JS part of the core is a single file, *LdtPlayer-core.js* compiled by concatenating JS files located dans *src/js*: + +### header.js ### + +Contains credits and licence information (The license is CEA, CNRS and Inria's *CeCILL-C*) + +### LAB.js ### + +see *external libraries*. + +### init.js ### + +Defines the *IriSP* object, used as a namespace for the whole Metadataplayer. +Contains the declaration and methods of the *IriSP.Metadataplayer* class, whose instantiation is the main entry point for the code. + +### pop.js ### + +Defines the *IriSP.PopcornReplacement* class, i.e. a simplified version of the Popcorn API used to interface with video players (jwplayer, dailymotion) not supported by Popcorn. +When this part of the Metadataplayer was written, Popcorn and jwplayer didn't interface well, but it should be replaced by a real Popcorn.js plugin. + +### utils.js ### + +Contains some utility functions such as *IriSP.loadCss*, an equivalent to LAB.js for CSS files. + +### model.js ### + +Contains classes managing the Cinelab data model, grouped in the *IriSP.Model* namespace. + +### widgets.js ### + +Contains the (abstract) class *IriSP.Widgets.Widget*, containing base functionalities for all widgets. + +### players ### + +Files in this directory interface *Popcorn Replacement* (see *pop.js*) with third-party video players. + +Five players are available: + +1. **player.jwplayer**, for JwPlayer, used to play RTMP streams on the *Ligne de temps* platform. +2. **player.dailymotion**, to play videos on Dailymotion. +3. **player.allocine**, to play videos on allocine.net +4. **player.mashup**, for the flash based mashup player written by Thibaut Cavalié. +5. **player.htmlMashup**, for the Popcorn-based HTML5 mashup player. + +### serializers ### + +Serializers are converters between the internal data representation in the metadata player and formats used for communication with servers. + +Two serializers are available: + +1. **ldt**, to read JSON projects provided by the *Lignes de Temps* platform. +2. **ldt\_annotate**, for communications with the Add Widget API, whose format is slightly different. + +## Widgets ## + +Widgets are modules, visible or not, adding functionalities to the Metadataplayer. + +Located in the *src/widgets* directory, they're composed of a mandatory JavaScript file, *WidgetName.js* and an optional stylesheet, *WidgetName.css* + +#### Common Widget Options #### + +- **metadata**, metadata source, as an object with the following properties: { url: *URL of the data source*, type: *Serializer type* } +- **container**, used to position the widget in a given HTML element, given its ID. If omitted, the widget will be automatically aligned vertically below the player. +- **annotation\_type**, in widgets displaying annotations. This option can have the following values: + - *String*: will display widgets whose annotation type title includes the string. Example: "segments" will show annotations whose annotation type have a title with "Segments" in it. + - *Array of string*: to display several annotation types. Example: "Segments" + - *false*: to display all annotations related to the media. + +Here's a list of available widgets: + +### HelloWorld ### + +- **Role**: Example widget demonstration the API capabilities +- **Options**: + - **text**: (default: "world"), text to display after "Hello, " +- Uses a CSS stylesheet: yes + +### Slider ### + +- **Role**: A combination of a Progress bar and a Slider displaying and allowing repositioning of the current video playback position. +- **Options**: + - **minimized\_height**: (default: 4), height in pixels of the *Slider* in minimized mode + - **maximized\_height**: (default: 10), height in pixels du *Slider* in maximized mode (on mouseover) + - **minimize\_timeout**: (default: 1500), duration in milliseconds before the *Slider* is automatically minimized. If set to 0, *Slider* stays maximized. +- Uses external library: jQuery UI +- Uses a CSS stylesheet: yes + +### Controller ### + +- **Role**: Play, Pause, Search, Annotate buttons and volume control +- **Options**: + - **disable\_annotate\_btn**: (default: false), disables Annotate button if set to *true* + - **disable\_search\_btn**: (default: true), disables Search button +- Uses external library: jQuery UI +- Uses a CSS stylesheet: yes + +### Arrow ### + +- **Role**: Draws the position arrow showing where the annotation is. +- **Options**: + - **arrow\_height**: (default: 16), arrow height in pixels + - **arrow\_width**: (default: 24), arrow width in pixels + - **base\_height**: (default: 0), distance between arrow bottom and widget button. Mandatory for a rounded widget. + - **base\_curve**: (default: 0), curvature radius in pixels for a rounded widget. + - **fill\_url**: fill image URL. + - **fill\_color**: (default: "#ffffff" = white), fill color. Can be replaced by a gradient described by : gradient angle-start color-end color, e.g.: "90-#000-#fff" + - **stroke\_color**: (default: "#b7b7b7" = grey), border color. + - **stroke\_width**: (default: 1.5), border width. + - **animation\_speed**: (default: 20), arrow animation speed. + - **pilot\_widget**: (default: "Annotation"), widget driving the arrow position. +- Uses external library: Raphael +- Uses a CSS stylesheet: no + +### Annotation ### + +- **Role**: Displays information relative to a single segment/annotation while it is being played +- **Options**: + - **annotation\_type**: (default: "chapitrage"), see *Common widget options*. + - **show\_top\_border**: (default: false), show top widget border (useful depending on whether it is used in combination with the *Arrow* widget) + - **site\_name**: "Lignes de Temps", site name to display when users click on "Share on social networks". +- Uses a CSS stylesheet: yes + +### CreateAnnotation ### + +- **Role**: Displays a form to create a new annotation +- **Options**: + - **show\_title\_field**: (default: true), shows or hides the annotation title field. + - **creator\_name**: Default annotation creator name. + - **creator\_avatar**: Creator profile thumbnail URL. + - **tag\_titles**: (default: false), list of tags to display, as an array of strings: [ "#firstTag", "#secondTag" ] + - **tags**: (default: false), list of tags to display, as an array of objects: [ { id: "tag-001", title: "#firstTag" } ]. Overrides *tag\_titles*. If both options are set to *false*, the most frequent tags in the project will be displayed. + - **max\_tags**: (default: 8), maximum number of tags to display. + - **polemics**: polemic buttons to display, as an array of objects, e.g.: [ { keyword: "++", background\_color: "#00a000", text\_color: "#ffffff" } ] + - **annotation\_type**: (default: "Contributions"), see *Common widget options*. + - **api\_serializer**: (default: "ldt\_annotate"), serializer to use when sending annotations. + - **api\_endpoint\_template**: API Endpoint URL, with {{id\}\} as a placeholder for project ID, e.g.: "http://ldt.iri.centrepompidou.fr/ldtplatform/api/ldt/annotations/{{id}}.json". + - **api\_method**: (default: "PUT"), HTTP method used to send annotations. *Lignes de temps* platform uses PUT. + - **close\_widget\_timeout**: (default: 0), duration in milliseconds before widget is closed after send. If value is set to 0, the widget stays open. +- Uses a CSS stylesheet: yes + +### Polemic ### + +- **Role**: Shows the *polemical timeline*, i.e. tweets colored according to the polemical syntax. Depending on the number of tweets, two visualization modes exist: + - Below the threshold (low volume mode), tweets are represented as individual squares. + - Above the threshold, columns show aggregated numbers of tweets by color. +- **Options**: + - **element\_width**: (default: 5), width in pixels of a tweet column. + - **element\_height**: (default: 5), height in pixels of a tweet, in low volume mode. + - **max\_elements**: (default: 15), threshold between low and high volume mode, in tweets per column. + - **annotation\_type**: (default: "tweet"), see *Common widget options*. + - **defaultcolor**: (default: "#585858" = grey), default color for tweets with no polemical coloring. + - **foundcolor**: (default: "#fc00ff" = magenta), color for tweets in a search result. + - **polemics**: polemical colors to display, as an array of objects, e.g. [ { name: "OK", keywords: [ "++" ], color: "#1D973D" } ] +- Uses a CSS stylesheet: yes + +### Tweet ### + +- **Role**: Show the contents on a tweet when clicj +- **Options**: + - **hide_timeout**: (default: 5000), durée en milliseconds, avant que l’affichage du Tweet ne se referme + - **polemics**: identique au paramètre *polemics* du widget *Polemic* + +### Sparkline ### + +- **Role**: Affiche une courbe indiquant l’évolution du volume d’annotations au cours du temps. +- **Options**: + - **annotation\_type**: see *Common widget options*, above + - **lineColor**: (default: "#7492b4" = gris-bleu), couleur de la courbe + - **fillColor**: (default: "#aeaeb8" = gris), couleur de la surface sous la courbe + - **lineWidth**: (default: 2), épaisseur en pixels de la courbe + - **slice\_count**: (default: 20), nombre des tranches horaires dans lesquelles les annotations sont réparties pour calculer la courbe + - **height**: (default: 50), hauteur en pixels de la courbe + - **margin**: (default: 5), marge en pixels au-dessus de la courbe +- Uses external library: Raphael +- Uses a CSS stylesheet: no + +### Tagcloud ### + +- **Role**: Shows a tag cloud - WARNING: Doesn't work well with Japanese language because of word splitting issues +- **Options**: + - **include\_titles**: (default: true), includes annotation titles when computing tag cloud. + - **include\_descriptions**: (default: true), includes annotation descriptions when computing tag cloud. + - **include\_tag\_texts**: (default: true), includes tags in annotations when computing tag cloud. + - **tag\_count**: (default: 30), maximum number of tags to display. + - **stopword\_language**: (default: "fr"), language code for the stopword list. + - **custom\_stopwords**: (default: []), custom stopwords to filter out. + - **exclude\_pattern**: (default: false), regexp to filter out. + - **annotation\_type**: (default: false), see *Common widget options*, above. The annotation type of the annotations whose text is extracted to compute the cloud. + - **segment\_annotation\_type**: (default: 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. + - **min\_font\_size**: (default: 10), taille de caractères (en pixels) pour le mot le moins fréquent. + - **max\_font\_size**: (default: 26), taille de caractères (en pixels) pour le mot le plus fréquent. +- Uses a CSS stylesheet: yes + +### AnnotationsList ### + +- **Role**: Show a list of annotations. +- **Options**: + - **ajax\_url**: (default: false), specifies an API template when annotations have to be loaded from an external source. In the URL, {{media}} will be replaced by the media ID, {{begin}} by the start *timecode* in milliseconds, {{end}} by the end *timecode* in milliseconds. If set to *false*, displayed annotations will be the ones loaded from the default metadata source. On the *Lignes de Temps*, the URL of the segments API is http://ldt.iri.centrepompidou.fr/ldtplatform/api/ldt/segments/{{media}}/{{begin}}/{{end}}?callback=? + - **ajax\_granularity**: (default: 300000 ms = 5 minutes), specifies the timespan to be loaded from the segment API, around the current timecode. + - **default\_thumbnail**: thumbnail to display when an annotation doesn't have one. + - **foreign\_url**: Specifies an URL template for when an annotation doesn't have an URL and is not in the current project. In that template, {{media}} will be replaced by the media ID, {{project}} by the project ID, {{annotationType}} by the annotation type ID and {{annotation}} by the annotation ID. For the *Lignes de temps* platform, this URL is http://ldt.iri.centrepompidou.fr/ldtplatform/ldt/front/player/{{media}}/{{project}}/{{annotationType}}#id={{annotation}} + - **annotation\_type**: (default: false), see *Common widget options*, above + - **refresh\_interval**: (default: 0), Ajax refresh interval, to get annotations added while watching (works with either the default source or the external segment API) + - **limit\_count**: (default: 10), Maximum number of annotations to display at once. + - **newest\_first**: (default: false), When *true*, annotations are sorted by decreasing creation date. When *false*, annotations are sorted by increasing timecode. +- Uses a CSS stylesheet: yes + +### Media ### + +- **Role**: Shows current media, as well as other medias in the project. Mostly used for mashups +- **Options**: + - **default\_thumbnail**: thumbnail to display when a media doesn't have one + - **media\_url\_template**: Specifies an URL template for when a media doesn't include URL information, e.g.: "http://ldt.iri.centrepompidou.fr/ldtplatform/ldt/front/player/{{media}}/" +- Uses a CSS stylesheet: yes + +### Tooltip ### + +- **Role**: Displays a tooltip. Is mainly used as a subwidget, embedded and called from another widget. +- No options +- Uses a CSS stylesheet: yes + +### Trace ### + +- **Role**: Sends traces to the KTBS server. +- **Options**: + - **js\_console**: (default: false), shows logs in the browser console. + - **url**: (default: "http://traces.advene.org:5000/"), URL of the trace server + - **requestmode**: (default: "GET"), HTTP method used to send traces (only *"GET"* allows *cross-domain* sending). + - **syncmode**: (default: "sync"), allows traces to be sent grouped (*"delayed"* mode) or as single events (*"sync"*). +- Uses external library: ktbs4js tracemanager +- Uses a CSS stylesheet: no + +### Mediafragment ### + +- **Role**: Handles *Media fragments*-compliant URIs (W3C Recommandation): Changing the playing position changes the URL and vice-versa. +- An URL ending with #id=*annotation ID* points to an annotation, one with #t=*time in seconds* to a precise position. +- No options +- Uses a CSS stylesheet: no + +### Social ### + +- **Role**: Adds buttons to share an URL on social networks +- **Options**: + - **text**: displays a text + - **url**: the URL to share + - **show_url**: Shows a button to copy/paste an URL + - **show_twitter**: Shows a button to share on Twitter + - **show_fb**: Shows a button to share on Facebook + - **show_gplus**: Shows a button to share on Google+ + - **show_mail**: Shows a button to share by e-mail +- Uses a CSS stylesheet: yes +- Uses external library: ZeroClipboard