| 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! :) |