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