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