git.sesse.net Git - vlc/blob - modules/codec/cmml/HACKING

   1 What's CMML?
   2 ------------
   3
   4 This is an implementation of the Continuous Media Markup Language
   5 (CMML) for VideoLAN.  In short, CMML is a (XML) markup language for
   6 time-continuous data, which of course includes multimedia such as
   7 video and audio.  It allows one to annotate a media file with both
   8 structured and unstructured textual data, but one of its distinguishing
   9 features--and what this code implements--is its support for embedding
  10 hyperlinks in media files.
  11
  12 So, while viewing some media (e.g. a radio interview with a band),
  13 you could provide a hyperlink to any URL, including a standard web
  14 page or other media (e.g. the band's home page).  The hyperlinks
  15 are active only for specific intervals of time while the media is
  16 playing, so for example during a radio interview, the hyperlinks
  17 can change depending on what questions the interviewer is asking
  18 and topic is being discussed.
  19
  20 For more general information on CMML and its role in the bigger
  21 picture of extending the World Wide Web to properly support multimedia,
  22 see <http://www.annodex.net/overview.html>.  For specifications of
  23 CMML, see <http://www.annodex.net/specifications.html>.
  24
  25
  26 Usage
  27 -----
  28
  29 Once you have hyperlinking capability, you take on some of the
  30 capabilities of a web browser, in particular following hyperlinks,
  31 and also maintaining a browsing history where you can go backwards
  32 and forwards between pieces of media you've linked to.  So, if you
  33 are viewing a file with CMML markup:
  34
  35 * Hyperlinks are displayed as a subtitle track
  36
  37 * Hyperlinks are followed with the VLC "activate" hotkey (by default,
  38   this is just the Enter key)
  39
  40 * Going back and forward are done with the "history-back" and
  41   "history-forward" keys, by default Cmd-[ and Cmd-] on Mac OS X,
  42   and Ctrl-[ and Ctrl-] on all other platforms.
  43
  44 Until the media browsing history features are made available outside
  45 of the CMML plugin, you can only use the history features while
  46 viewing a file that contains CMML markup: e.g. you cannot navigate
  47 backwards or forward in the history while viewing a standard MPEG
  48 video.  This is a limitation which may be removed if the media
  49 browsing code is merged into the VLC core.
  50
  51
  52 Overview of the code
  53 --------------------
  54
  55 First: a lot of this code could be implemented, or should be
  56 implemented, in VLC's core (libvlc) rather than be part of a codec
  57 plugin, either because it's something which really should belong
  58 in the core (e.g. media browsing history, system-indepedent interface
  59 to web browser) or a generally useful thing outside of the codec
  60 plugin (e.g. XML parser, URL handling library).  That's well and
  61 good, but changes to libvlc are far-reaching and affect all of VLC,
  62 rather than only affecting a single plugin.  It's sensible to
  63 gradually merge this stuff into libvlc on an as-needs basis, rather
  64 than trying to refactor out huge amounts of code at once.
  65
  66 Here's a quick overview of what the files do:
  67
  68 * browser_open.[ch]: A very simple attempt to provide a way to
  69   open the system's web browser.
  70
  71 * history.[ch]: Media browsing history (as described above in
  72   "Usage").
  73
  74 * xstrcat.h: Simple wrapper around strcat(1) which performs a
  75   realloc(1) if needed.
  76
  77 * xarray.[ch]: extensible (growable) array, similar to a Vector in
  78   Java/C++.  Could be replaced with a vlc_list_t from libvlc's
  79   src/misc/objects.c if the vlc_list_t API were made public.
  80
  81 * xlist.[ch]: Yet Another Linked List implementation (sorry guys
  82   :), only here because XTag (see below) uses it internally.
  83
  84 * xtag.[ch]: A very simple (but working!), lightweight XML
  85   parser.
  86
  87 * xurl.[ch]: A small URL handling library.
  88
  89 * cmml.c: The actual 'codec' parser, which parses the CMML data
  90   (demuxed from the incoming media stream, of course), and provides
  91   two VLC vars ("psz-current-anchor-description" and
  92   "psz-current-anchor-url") which enable intf plugins to display
  93   the CMML data to the user and let them interact with it.
  94
  95 * intf.c: Enables media browsing functionality by displaying
  96   hyperlinks as a subtitle track, and responding to user
  97   keypresses for following hyperlinks and navigating the media
  98   browsing history.
  99
 100 So, all the files except for cmml.c and intf.c could be made available
 101 and re-used outside of this plugin, but currently are not (for the
 102 reasons given above).
 103