docs/source/siteadmin/media-types.rst

   1 .. MediaGoblin Documentation
   2
   3    Written in 2011, 2012, 2014 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 six additional media types: video, audio,
  22 raw image, 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 Raw image
 153 =========
 154
 155 To enable raw image you need to install pyexiv2.  On Debianoid systems
 156
 157 .. code-block:: bash
 158
 159     sudo apt-get install python-pyexiv2
 160
 161 Add ``[[mediagoblin.media_types.raw_image]]`` under the ``[plugins]``
 162 section in your ``mediagoblin_local.ini`` and restart MediaGoblin.
 163
 164 Run
 165
 166 .. code-block:: bash
 167
 168     ./bin/gmg dbupdate
 169
 170 Now you should be able to submit raw images, and mediagoblin should
 171 extract the JPEG preview from them.
 172
 173
 174 Ascii art
 175 =========
 176
 177 To enable ascii art support, first install the
 178 `chardet <http://pypi.python.org/pypi/chardet>`_
 179 library, which is necessary for creating thumbnails of ascii art
 180
 181 .. code-block:: bash
 182
 183     ./bin/easy_install chardet
 184
 185
 186 Next, modify (and possibly copy over from ``mediagoblin.ini``) your
 187 ``mediagoblin_local.ini``.  In the ``[plugins]`` section, add
 188 ``[[mediagoblin.media_types.ascii]]``.
 189
 190 Run
 191
 192 .. code-block:: bash
 193
 194     ./bin/gmg dbupdate
 195
 196 Now any .txt file you uploaded will be processed as ascii art!
 197
 198
 199 STL / 3d model support
 200 ======================
 201
 202 To enable the "STL" 3d model support plugin, first make sure you have
 203 a recentish `Blender <http://blender.org>`_ installed and available on
 204 your execution path.  This feature has been tested with Blender 2.63.
 205 It may work on some earlier versions, but that is not guaranteed (and
 206 is surely not to work prior to Blender 2.5X).
 207
 208 Add ``[[mediagoblin.media_types.stl]]`` under the ``[plugins]`` section in your
 209 ``mediagoblin_local.ini`` and restart MediaGoblin.
 210
 211 Run
 212
 213 .. code-block:: bash
 214
 215     ./bin/gmg dbupdate
 216
 217 You should now be able to upload .obj and .stl files and MediaGoblin
 218 will be able to present them to your wide audience of admirers!
 219
 220 PDF and Document
 221 ================
 222
 223 To enable the "PDF and Document" support plugin, you need:
 224
 225 1. pdftocairo and pdfinfo for pdf only support.
 226
 227 2. unoconv with headless support to support converting libreoffice supported
 228    documents as well, such as doc/ppt/xls/odf/odg/odp and more.
 229    For the full list see mediagoblin/media_types/pdf/processing.py,
 230    unoconv_supported.
 231
 232 All executables must be on your execution path.
 233
 234 To install this on Fedora:
 235
 236 .. code-block:: bash
 237
 238     sudo yum install -y poppler-utils unoconv libreoffice-headless
 239
 240 Note: You can leave out unoconv and libreoffice-headless if you want only pdf
 241 support. This will result in a much smaller list of dependencies.
 242
 243 pdf.js relies on git submodules, so be sure you have fetched them:
 244
 245 .. code-block:: bash
 246
 247     git submodule init
 248     git submodule update
 249
 250 This feature has been tested on Fedora with:
 251  poppler-utils-0.20.2-9.fc18.x86_64
 252  unoconv-0.5-2.fc18.noarch
 253  libreoffice-headless-3.6.5.2-8.fc18.x86_64
 254
 255 It may work on some earlier versions, but that is not guaranteed.
 256
 257 Add ``[[mediagoblin.media_types.pdf]]`` under the ``[plugins]`` section in your
 258 ``mediagoblin_local.ini`` and restart MediaGoblin.
 259
 260 Run
 261
 262 .. code-block:: bash
 263
 264     ./bin/gmg dbupdate
 265
 266
 267 Blog (HIGHLY EXPERIMENTAL)
 268 ==========================
 269
 270 MediaGoblin has a blog media type, which you might notice by looking
 271 through the docs!  However, it is *highly experimental*.  We have not
 272 security reviewed this, and it acts in a way that is not like normal
 273 blogs (the blogposts are themselves media types!).
 274
 275 So you can play with this, but it is not necessarily recommended yet
 276 for production use! :)