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 require **additional dependencies** that you will have to install. You
  36 will find descriptions on how to satisfy the requirements of each media type
  37 below.
  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. If you have
  48 deployed MediaGoblin as an unprivileged user as described in
  49 ":doc:`production-deployments`", you'll first need to switch to this account::
  50
  51     sudo su mediagoblin --shell=/bin/bash
  52     $ cd /srv/mediagoblin.example.org/mediagoblin
  53
  54 Now run dbupdate::
  55
  56     $ ./bin/gmg dbupdate
  57
  58 If you are running an active site, depending on your server
  59 configuration, you may need to stop it first (and it's certainly a
  60 good idea to restart it after the update).
  61
  62
  63 How does MediaGoblin decide which media type to use for a file?
  64 ===============================================================
  65
  66 MediaGoblin has two methods for finding the right media type for an uploaded
  67 file. One is based on the file extension of the uploaded file; every media type
  68 maintains a list of supported file extensions. The second is based on a sniffing
  69 handler, where every media type may inspect the uploaded file and tell if it
  70 will accept it.
  71
  72 The file-extension-based approach is used before the sniffing-based approach,
  73 if the file-extension-based approach finds a match, the sniffing-based approach
  74 will be skipped as it uses far more processing power.
  75
  76 Configuring Media Types
  77 =======================
  78
  79 Each media type has a ``config_spec.ini`` file with configurable
  80 options and comments explaining their intended side effect. For
  81 instance the ``video`` media type configuration can be found in
  82 ``mediagoblin/media_types/video/config_spec.ini``.
  83
  84
  85 Audio
  86 =====
  87
  88 To enable audio, install the GStreamer and python-gstreamer bindings (as well
  89 as whatever GStreamer plugins you want, good/bad/ugly):
  90
  91 .. code-block:: bash
  92
  93     # Debian and co.
  94     sudo apt install python3-gst-1.0 gstreamer1.0-plugins-{base,bad,good,ugly} \
  95     gstreamer1.0-libav
  96
  97     # Fedora and co.
  98     sudo dnf install gstreamer1-plugins-{base,bad-free,good,ugly-free}
  99
 100 Add ``[[mediagoblin.media_types.audio]]`` under the ``[plugins]`` section in your
 101 ``mediagoblin.ini`` and update MediaGoblin::
 102
 103     $ ./bin/gmg dbupdate
 104
 105 Restart MediaGoblin (and Celery if applicable). You should now be able to upload
 106 and listen to audio files!
 107
 108 On production deployments, you will need to increase Nginx's
 109 ``client_max_body_size`` to allow larger files to be uploaded, or you'll get a
 110 "413 Request Entity Too Large" error. See ":ref:`webserver-config`".
 111
 112 Production deployments will also need a separate process to transcode media in
 113 the background. See ":ref:`systemd-service-files`" and
 114 ":ref:`separate-celery`" sections of this manual.
 115
 116 .. note::
 117
 118    MediaGoblin previously generated spectrograms for uploaded audio. This
 119    feature has been removed due to incompatibility with Python 3. We may
 120    consider re-adding this feature in the future.
 121
 122
 123 Video
 124 =====
 125
 126 To enable video, first install GStreamer and the python-gstreamer
 127 bindings (as well as whatever GStreamer extensions you want,
 128 good/bad/ugly):
 129
 130 .. code-block:: bash
 131
 132     # Debian and co.
 133     sudo apt install python3-gi gstreamer1.0-tools gir1.2-gstreamer-1.0 \
 134     gir1.2-gst-plugins-base-1.0 gstreamer1.0-plugins-{good,bad,ugly} \
 135     gstreamer1.0-libav python3-gst-1.0
 136
 137 .. note::
 138
 139    We unfortunately do not have working installation instructions for Fedora and
 140    co. Some incomplete information is available on the `Hacking Howto wiki page <http://wiki.mediagoblin.org/HackingHowto#Fedora_.2F_RedHat.28.3F.29_.2F_CentOS>`_
 141
 142 Add ``[[mediagoblin.media_types.video]]`` under the ``[plugins]`` section in
 143 your ``mediagoblin.ini`` and restart MediaGoblin.
 144
 145 Run::
 146
 147     $ ./bin/gmg dbupdate
 148
 149 Restart MediaGoblin (and Celery if applicable). Now you should be able to submit
 150 videos, and MediaGoblin should transcode them.
 151
 152 On production deployments, you will need to increase Nginx's
 153 ``client_max_body_size`` to allow larger files to be uploaded, or you'll get a
 154 "413 Request Entity Too Large" error. See ":ref:`webserver-config`".
 155
 156 Production deployments will also need a separate process to transcode media in
 157 the background. To set that up, check out the ":doc:`deploying`" and
 158 ":doc:`production-deployments`" sections of this manual.
 159
 160
 161 Raw image
 162 =========
 163
 164 To enable raw image you need to install pyexiv2::
 165
 166     # Debian and co.
 167     sudo apt install python3-pyexiv2
 168
 169 Add ``[[mediagoblin.media_types.raw_image]]`` under the ``[plugins]``
 170 section in your ``mediagoblin.ini`` and restart MediaGoblin.
 171
 172 Run::
 173
 174     $ ./bin/gmg dbupdate
 175
 176 Restart MediaGoblin (and Celery if applicable). Now you should be able to submit
 177 raw images, and MediaGoblin should extract the JPEG preview from them.
 178
 179
 180 ASCII art
 181 =========
 182
 183 To enable ASCII art support, first install the
 184 `chardet <http://pypi.python.org/pypi/chardet>`_
 185 library, which is necessary for creating thumbnails of ASCII art::
 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     $ ./bin/gmg dbupdate
 196
 197 Restart MediaGoblin (and Celery if applicable). Now any .txt file you uploaded
 198 will be processed as ASCII art!
 199
 200
 201 STL / 3D model support
 202 ======================
 203
 204 To enable the "STL" 3D model support plugin, first make sure you have
 205 a recent `Blender <http://blender.org>`_ installed and available on
 206 your execution path.  This feature has been tested with Blender 2.63.
 207 It may work on some earlier versions, but that is not guaranteed (and
 208 is surely not to work prior to Blender 2.5X).
 209
 210 Add ``[[mediagoblin.media_types.stl]]`` under the ``[plugins]`` section in your
 211 ``mediagoblin.ini`` and restart MediaGoblin.
 212
 213 Run::
 214
 215     $ ./bin/gmg dbupdate
 216
 217 Restart MediaGoblin (and Celery if applicable). You should now be able to upload
 218 .obj and .stl files and MediaGoblin will be able to present them to your wide
 219 audience of admirers!
 220
 221
 222 PDF and Document
 223 ================
 224
 225 To enable the "PDF and Document" support plugin, you need:
 226
 227 1. pdftocairo and pdfinfo for PDF only support.
 228
 229 2. unoconv with headless support to support converting LibreOffice supported
 230    documents as well, such as doc/ppt/xls/odf/odg/odp and more.
 231    For the full list see mediagoblin/media_types/pdf/processing.py,
 232    unoconv_supported.
 233
 234 All executables must be on your execution path.
 235
 236 To install this on Fedora::
 237
 238     sudo dnf install 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     $ git submodule init
 246     $ git submodule update
 247
 248 This feature has been tested on Fedora with:
 249  poppler-utils-0.20.2-9.fc18.x86_64
 250  unoconv-0.5-2.fc18.noarch
 251  libreoffice-headless-3.6.5.2-8.fc18.x86_64
 252
 253 It may work on some earlier versions, but that is not guaranteed.
 254
 255 Add ``[[mediagoblin.media_types.pdf]]`` under the ``[plugins]`` section in your
 256 ``mediagoblin.ini`` and restart MediaGoblin.
 257
 258 Run::
 259
 260     $ ./bin/gmg dbupdate
 261
 262
 263 Blog (HIGHLY EXPERIMENTAL)
 264 ==========================
 265
 266 MediaGoblin has a blog media type, which you might notice by looking
 267 through the docs!  However, it is *highly experimental*.  We have not
 268 security reviewed this, and it acts in a way that is not like normal
 269 blogs (the blog posts are themselves media types!).
 270
 271 So you can play with this, but it is not necessarily recommended yet
 272 for production use! :)