docs/source/siteadmin/media-types.rst

   1 .. MediaGoblin Documentation
   2
   3    Written in 2011, 2012 by MediaGoblin contributors
   4
   5    To the extent possible under law, the author(s) have dedicated all
   6    copyright and related and neighboring rights to this software to
   7    the public domain worldwide. This software is distributed without
   8    any warranty.
   9
  10    You should have received a copy of the CC0 Public Domain
  11    Dedication along with this software. If not, see
  12    <http://creativecommons.org/publicdomain/zero/1.0/>.
  13
  14 .. _media-types-chapter:
  15
  16 ====================
  17 Media Types
  18 ====================
  19
  20 In the future, there will be all sorts of media types you can enable,
  21 but in the meanwhile there are five additional media types: video, audio,
  22 ascii art, STL/3d models, PDF and Document.
  23
  24 First, you should probably read ":doc:`configuration`" to make sure
  25 you know how to modify the mediagoblin config file.
  26
  27 Enabling Media Types
  28 ====================
  29
  30 .. note::
  31     Media types are now plugins
  32
  33 Media types are enabled in your mediagoblin configuration file, typically it is
  34 created by copying ``mediagoblin.ini`` to ``mediagoblin_local.ini`` and then
  35 applying your changes to ``mediagoblin_local.ini``. If you don't already have a
  36 ``mediagoblin_local.ini``, create one in the way described.
  37
  38 Most media types have additional dependencies that you will have to install.
  39 You will find descriptions on how to satisfy the requirements of each media type
  40 on this page.
  41
  42 To enable a media type, add the the media type under the ``[plugins]`` section
  43 in you ``mediagoblin_local.ini``. For example, if your system supported image
  44 and video media types, then it would look like this::
  45
  46     [plugins]
  47     [[mediagoblin.media_types.image]]
  48     [[mediagoblin.media_types.video]]
  49
  50 Note that after enabling new media types, you must run dbupdate like so::
  51
  52     ./bin/gmg dbupdate
  53
  54 If you are running an active site, depending on your server
  55 configuration, you may need to stop it first (and it's certainly a
  56 good idea to restart it after the update).
  57
  58
  59 How does MediaGoblin decide which media type to use for a file?
  60 ===============================================================
  61
  62 MediaGoblin has two methods for finding the right media type for an uploaded
  63 file. One is based on the file extension of the uploaded file; every media type
  64 maintains a list of supported file extensions. The second is based on a sniffing
  65 handler, where every media type may inspect the uploaded file and tell if it
  66 will accept it.
  67
  68 The file-extension-based approach is used before the sniffing-based approach,
  69 if the file-extension-based approach finds a match, the sniffing-based approach
  70 will be skipped as it uses far more processing power.
  71
  72
  73 Video
  74 =====
  75
  76 To enable video, first install gstreamer and the python-gstreamer
  77 bindings (as well as whatever gstremaer extensions you want,
  78 good/bad/ugly).  On Debianoid systems
  79
  80 .. code-block:: bash
  81
  82     sudo apt-get install python-gst0.10 \
  83         gstreamer0.10-plugins-base \
  84         gstreamer0.10-plugins-bad \
  85         gstreamer0.10-plugins-good \
  86         gstreamer0.10-plugins-ugly \
  87         gstreamer0.10-ffmpeg
  88
  89
  90 Add ``[[mediagoblin.media_types.video]]`` under the ``[plugins]`` section in
  91 your ``mediagoblin_local.ini`` and restart MediaGoblin.
  92
  93 Run
  94
  95 .. code-block:: bash
  96
  97     ./bin/gmg dbupdate
  98
  99 Now you should be able to submit videos, and mediagoblin should
 100 transcode them.
 101
 102 .. note::
 103
 104    You almost certainly want to separate Celery from the normal
 105    paste process or your users will probably find that their connections
 106    time out as the video transcodes.  To set that up, check out the
 107    ":doc:`production-deployments`" section of this manual.
 108
 109
 110 Audio
 111 =====
 112
 113 To enable audio, install the gstreamer and python-gstreamer bindings (as well
 114 as whatever gstreamer plugins you want, good/bad/ugly), scipy and numpy are
 115 also needed for the audio spectrograms.
 116 To install these on Debianoid systems, run::
 117
 118     sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \
 119         gstreamer0.10-ffmpeg python-numpy python-scipy
 120
 121 The ``scikits.audiolab`` package you will install in the next step depends on the
 122 ``libsndfile1-dev`` package, so we should install it.
 123 On Debianoid systems, run
 124
 125 .. code-block:: bash
 126
 127     sudo apt-get install libsndfile1-dev
 128
 129 .. note::
 130     scikits.audiolab will display a warning every time it's imported if you do
 131     not compile it with alsa support. Alsa support is not necessary for the GNU
 132     MediaGoblin application but if you do not wish the alsa warnings from
 133     audiolab you should also install ``libasound2-dev`` before installing
 134     scikits.audiolab.
 135
 136 Then install ``scikits.audiolab`` for the spectrograms::
 137
 138     ./bin/pip install scikits.audiolab
 139
 140 Add ``[[mediagoblin.media_types.audio]]`` under the ``[plugins]`` section in your
 141 ``mediagoblin_local.ini`` and restart MediaGoblin.
 142
 143 Run
 144
 145 .. code-block:: bash
 146
 147     ./bin/gmg dbupdate
 148
 149 You should now be able to upload and listen to audio files!
 150
 151
 152 Ascii art
 153 =========
 154
 155 To enable ascii art support, first install the
 156 `chardet <http://pypi.python.org/pypi/chardet>`_
 157 library, which is necessary for creating thumbnails of ascii art
 158
 159 .. code-block:: bash
 160
 161     ./bin/easy_install chardet
 162
 163
 164 Next, modify (and possibly copy over from ``mediagoblin.ini``) your
 165 ``mediagoblin_local.ini``.  In the ``[plugins]`` section, add
 166 ``[[mediagoblin.media_types.ascii]]``.
 167
 168 Run
 169
 170 .. code-block:: bash
 171
 172     ./bin/gmg dbupdate
 173
 174 Now any .txt file you uploaded will be processed as ascii art!
 175
 176
 177 STL / 3d model support
 178 ======================
 179
 180 To enable the "STL" 3d model support plugin, first make sure you have
 181 a recentish `Blender <http://blender.org>`_ installed and available on
 182 your execution path.  This feature has been tested with Blender 2.63.
 183 It may work on some earlier versions, but that is not guaranteed (and
 184 is surely not to work prior to Blender 2.5X).
 185
 186 Add ``[[mediagoblin.media_types.stl]]`` under the ``[plugins]`` section in your
 187 ``mediagoblin_local.ini`` and restart MediaGoblin.
 188
 189 Run
 190
 191 .. code-block:: bash
 192
 193     ./bin/gmg dbupdate
 194
 195 You should now be able to upload .obj and .stl files and MediaGoblin
 196 will be able to present them to your wide audience of admirers!
 197
 198 PDF and Document
 199 ================
 200
 201 To enable the "PDF and Document" support plugin, you need:
 202
 203 1. pdftocairo and pdfinfo for pdf only support.
 204
 205 2. unoconv with headless support to support converting libreoffice supported
 206    documents as well, such as doc/ppt/xls/odf/odg/odp and more.
 207    For the full list see mediagoblin/media_types/pdf/processing.py,
 208    unoconv_supported.
 209
 210 All executables must be on your execution path.
 211
 212 To install this on Fedora:
 213
 214 .. code-block:: bash
 215
 216     sudo yum install -y poppler-utils unoconv libreoffice-headless
 217
 218 Note: You can leave out unoconv and libreoffice-headless if you want only pdf
 219 support. This will result in a much smaller list of dependencies.
 220
 221 pdf.js relies on git submodules, so be sure you have fetched them:
 222
 223 .. code-block:: bash
 224
 225     git submodule init
 226     git submodule update
 227
 228 This feature has been tested on Fedora with:
 229  poppler-utils-0.20.2-9.fc18.x86_64
 230  unoconv-0.5-2.fc18.noarch
 231  libreoffice-headless-3.6.5.2-8.fc18.x86_64
 232
 233 It may work on some earlier versions, but that is not guaranteed.
 234
 235 Add ``[[mediagoblin.media_types.pdf]]`` under the ``[plugins]`` section in your
 236 ``mediagoblin_local.ini`` and restart MediaGoblin.
 237
 238 Run
 239
 240 .. code-block:: bash
 241
 242     ./bin/gmg dbupdate
 243
 244