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.
  34
  35 Most media types have additional dependencies that you will have to install.
  36 You will find descriptions on how to satisfy the requirements of each media type
  37 on this page.
  38
  39 To enable a media type, add the the media type under the ``[plugins]`` section
  40 in you ``mediagoblin.ini``. For example, if your system supported image
  41 and video media types, then it would look like this::
  42
  43     [plugins]
  44     [[mediagoblin.media_types.image]]
  45     [[mediagoblin.media_types.video]]
  46
  47 Note that after enabling new media types, you must run dbupdate like so::
  48
  49     ./bin/gmg dbupdate
  50
  51 If you are running an active site, depending on your server
  52 configuration, you may need to stop it first (and it's certainly a
  53 good idea to restart it after the update).
  54
  55
  56 How does MediaGoblin decide which media type to use for a file?
  57 ===============================================================
  58
  59 MediaGoblin has two methods for finding the right media type for an uploaded
  60 file. One is based on the file extension of the uploaded file; every media type
  61 maintains a list of supported file extensions. The second is based on a sniffing
  62 handler, where every media type may inspect the uploaded file and tell if it
  63 will accept it.
  64
  65 The file-extension-based approach is used before the sniffing-based approach,
  66 if the file-extension-based approach finds a match, the sniffing-based approach
  67 will be skipped as it uses far more processing power.
  68
  69 Configuring Media Types
  70 =======================
  71
  72 Each media type has a ``config_spec.ini`` file with configurable
  73 options and comments explaining their intended side effect. For
  74 instance the ``video`` media type configuration can be found in
  75 ``mediagoblin/media_types/video/config_spec.ini``.
  76
  77
  78 Video
  79 =====
  80
  81 To enable video, first install GStreamer and the python-gstreamer
  82 bindings (as well as whatever GStreamer extensions you want,
  83 good/bad/ugly).  On Debianoid systems
  84
  85 .. code-block:: bash
  86
  87     sudo apt-get install python-gi python3-gi \
  88         gstreamer1.0-tools \
  89         gir1.2-gstreamer-1.0 \
  90         gir1.2-gst-plugins-base-1.0 \
  91         gstreamer1.0-plugins-good \
  92         gstreamer1.0-plugins-ugly \
  93         gstreamer1.0-plugins-bad \
  94         gstreamer1.0-libav \
  95         python-gst-1.0
  96
  97
  98 Add ``[[mediagoblin.media_types.video]]`` under the ``[plugins]`` section in
  99 your ``mediagoblin.ini`` and restart MediaGoblin.
 100
 101 Run
 102
 103 .. code-block:: bash
 104
 105     ./bin/gmg dbupdate
 106
 107 Now you should be able to submit videos, and MediaGoblin should
 108 transcode them.
 109
 110 .. note::
 111
 112    You almost certainly want to separate Celery from the normal
 113    paste process or your users will probably find that their connections
 114    time out as the video transcodes.  To set that up, check out the
 115    ":doc:`production-deployments`" section of this manual.
 116
 117
 118 Audio
 119 =====
 120
 121 To enable audio, install the GStreamer and python-gstreamer bindings (as well
 122 as whatever GStreamer plugins you want, good/bad/ugly), SciPy and NumPy are
 123 also needed for the audio spectrograms.
 124 To install these on Debianoid systems, run::
 125
 126     sudo apt-get install python-gst-1.0 gstreamer1.0-plugins-{base,bad,good,ugly} \
 127     gstreamer1.0-libav python-numpy python-scipy libsndfile1-dev libasound2-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.
 133
 134 If you're running Python 2, install ``scikits.audiolab`` for the spectrograms::
 135
 136 .. code-block:: bash
 137
 138     ./bin/pip install numpy==1.9.1
 139     ./bin/pip install scikits.audiolab==0.10.2
 140
 141 For Python 3 ``scikits.audiolab`` has no package yet. Instead of the cool
 142 specrogram image a static icon is used until we found a replacement. (#5467)
 143
 144 Add ``[[mediagoblin.media_types.audio]]`` under the ``[plugins]`` section in your
 145 ``mediagoblin.ini`` and restart MediaGoblin.
 146
 147 Run
 148
 149 .. code-block:: bash
 150
 151     ./bin/gmg dbupdate
 152
 153 You should now be able to upload and listen to audio files!
 154
 155
 156 Raw image
 157 =========
 158
 159 To enable raw image you need to install pyexiv2.  On Debianoid systems
 160
 161 .. code-block:: bash
 162
 163     sudo apt-get install python-pyexiv2
 164
 165 Add ``[[mediagoblin.media_types.raw_image]]`` under the ``[plugins]``
 166 section in your ``mediagoblin.ini`` and restart MediaGoblin.
 167
 168 Run
 169
 170 .. code-block:: bash
 171
 172     ./bin/gmg dbupdate
 173
 174 Now you should be able to submit raw images, and MediaGoblin should
 175 extract the JPEG preview from them.
 176
 177
 178 ASCII art
 179 =========
 180
 181 To enable ASCII art support, first install the
 182 `chardet <http://pypi.python.org/pypi/chardet>`_
 183 library, which is necessary for creating thumbnails of ASCII art
 184
 185 .. code-block:: bash
 186
 187     ./bin/easy_install chardet
 188
 189
 190 Next, modify your ``mediagoblin.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 recent `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.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.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 blog posts are themselves media types!).
 277
 278 So you can play with this, but it is not necessarily recommended yet
 279 for production use! :)