docs/source/siteadmin/media-types.rst

   1 .. MediaGoblin Documentation
   2
   3    Written in 2011, 2012, 2014, 2015 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 Configuring Media Types
  73 =======================
  74
  75 Each media type has a ``config_spec.ini`` file with configurable
  76 options and comments explaining their intended side effect. For
  77 instance the ``video`` media type configuration can be found in
  78 ``mediagoblin/media_types/video/config_spec.ini``.
  79
  80
  81 Video
  82 =====
  83
  84 To enable video, first install gstreamer and the python-gstreamer
  85 bindings (as well as whatever gstremaer extensions you want,
  86 good/bad/ugly).  On Debianoid systems
  87
  88 .. code-block:: bash
  89
  90     sudo apt-get install python-gi python3-gi \
  91         gstreamer1.0-tools \
  92         gir1.2-gstreamer-1.0 \
  93         gir1.2-gst-plugins-base-1.0 \
  94         gstreamer1.0-plugins-good \
  95         gstreamer1.0-plugins-ugly \
  96         gstreamer1.0-plugins-bad \
  97         gstreamer1.0-libav \
  98         python-gst-1.0
  99
 100
 101 Add ``[[mediagoblin.media_types.video]]`` under the ``[plugins]`` section in
 102 your ``mediagoblin_local.ini`` and restart MediaGoblin.
 103
 104 Run
 105
 106 .. code-block:: bash
 107
 108     ./bin/gmg dbupdate
 109
 110 Now you should be able to submit videos, and mediagoblin should
 111 transcode them.
 112
 113 .. note::
 114
 115    You almost certainly want to separate Celery from the normal
 116    paste process or your users will probably find that their connections
 117    time out as the video transcodes.  To set that up, check out the
 118    ":doc:`production-deployments`" section of this manual.
 119
 120
 121 Audio
 122 =====
 123
 124 To enable audio, install the gstreamer and python-gstreamer bindings (as well
 125 as whatever gstreamer plugins you want, good/bad/ugly), scipy and numpy are
 126 also needed for the audio spectrograms.
 127 To install these on Debianoid systems, run::
 128
 129     sudo apt-get install python-gst-1.0 gstreamer1.0-plugins-{base,bad,good,ugly} \
 130     gstreamer1.0-libav python-numpy python-scipy libsndfile1-dev libasound2-dev
 131
 132 .. note::
 133     scikits.audiolab will display a warning every time it's imported if you do
 134     not compile it with alsa support. Alsa support is not necessary for the GNU
 135     MediaGoblin application.
 136
 137 Then install ``scikits.audiolab`` for the spectrograms::
 138
 139     ./bin/pip install scikits.audiolab
 140
 141 Add ``[[mediagoblin.media_types.audio]]`` under the ``[plugins]`` section in your
 142 ``mediagoblin_local.ini`` and restart MediaGoblin.
 143
 144 Run
 145
 146 .. code-block:: bash
 147
 148     ./bin/gmg dbupdate
 149
 150 You should now be able to upload and listen to audio files!
 151
 152
 153 Raw image
 154 =========
 155
 156 To enable raw image you need to install pyexiv2.  On Debianoid systems
 157
 158 .. code-block:: bash
 159
 160     sudo apt-get install python-pyexiv2
 161
 162 Add ``[[mediagoblin.media_types.raw_image]]`` under the ``[plugins]``
 163 section in your ``mediagoblin_local.ini`` and restart MediaGoblin.
 164
 165 Run
 166
 167 .. code-block:: bash
 168
 169     ./bin/gmg dbupdate
 170
 171 Now you should be able to submit raw images, and mediagoblin should
 172 extract the JPEG preview from them.
 173
 174
 175 Ascii art
 176 =========
 177
 178 To enable ascii art support, first install the
 179 `chardet <http://pypi.python.org/pypi/chardet>`_
 180 library, which is necessary for creating thumbnails of ascii art
 181
 182 .. code-block:: bash
 183
 184     ./bin/easy_install chardet
 185
 186
 187 Next, modify (and possibly copy over from ``mediagoblin.ini``) your
 188 ``mediagoblin_local.ini``.  In the ``[plugins]`` section, add
 189 ``[[mediagoblin.media_types.ascii]]``.
 190
 191 Run
 192
 193 .. code-block:: bash
 194
 195     ./bin/gmg dbupdate
 196
 197 Now any .txt file you uploaded will be processed as ascii art!
 198
 199
 200 STL / 3d model support
 201 ======================
 202
 203 To enable the "STL" 3d model support plugin, first make sure you have
 204 a recentish `Blender <http://blender.org>`_ installed and available on
 205 your execution path.  This feature has been tested with Blender 2.63.
 206 It may work on some earlier versions, but that is not guaranteed (and
 207 is surely not to work prior to Blender 2.5X).
 208
 209 Add ``[[mediagoblin.media_types.stl]]`` under the ``[plugins]`` section in your
 210 ``mediagoblin_local.ini`` and restart MediaGoblin.
 211
 212 Run
 213
 214 .. code-block:: bash
 215
 216     ./bin/gmg dbupdate
 217
 218 You should now be able to upload .obj and .stl files and MediaGoblin
 219 will be able to present them to your wide audience of admirers!
 220
 221 PDF and Document
 222 ================
 223
 224 To enable the "PDF and Document" support plugin, you need:
 225
 226 1. pdftocairo and pdfinfo for pdf only support.
 227
 228 2. unoconv with headless support to support converting libreoffice supported
 229    documents as well, such as doc/ppt/xls/odf/odg/odp and more.
 230    For the full list see mediagoblin/media_types/pdf/processing.py,
 231    unoconv_supported.
 232
 233 All executables must be on your execution path.
 234
 235 To install this on Fedora:
 236
 237 .. code-block:: bash
 238
 239     sudo yum install -y poppler-utils unoconv libreoffice-headless
 240
 241 Note: You can leave out unoconv and libreoffice-headless if you want only pdf
 242 support. This will result in a much smaller list of dependencies.
 243
 244 pdf.js relies on git submodules, so be sure you have fetched them:
 245
 246 .. code-block:: bash
 247
 248     git submodule init
 249     git submodule update
 250
 251 This feature has been tested on Fedora with:
 252  poppler-utils-0.20.2-9.fc18.x86_64
 253  unoconv-0.5-2.fc18.noarch
 254  libreoffice-headless-3.6.5.2-8.fc18.x86_64
 255
 256 It may work on some earlier versions, but that is not guaranteed.
 257
 258 Add ``[[mediagoblin.media_types.pdf]]`` under the ``[plugins]`` section in your
 259 ``mediagoblin_local.ini`` and restart MediaGoblin.
 260
 261 Run
 262
 263 .. code-block:: bash
 264
 265     ./bin/gmg dbupdate
 266
 267
 268 Blog (HIGHLY EXPERIMENTAL)
 269 ==========================
 270
 271 MediaGoblin has a blog media type, which you might notice by looking
 272 through the docs!  However, it is *highly experimental*.  We have not
 273 security reviewed this, and it acts in a way that is not like normal
 274 blogs (the blogposts are themselves media types!).
 275
 276 So you can play with this, but it is not necessarily recommended yet
 277 for production use! :)