Commit | Line | Data |
---|---|---|
473a4431 CAW |
1 | .. MediaGoblin Documentation |
2 | ||
8af91cea | 3 | Written in 2011, 2012, 2014, 2015 by MediaGoblin contributors |
473a4431 CAW |
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 | ||
9bc2fc6c CAW |
14 | .. _media-types-chapter: |
15 | ||
16 | ==================== | |
d34757dc | 17 | Media Types |
9bc2fc6c CAW |
18 | ==================== |
19 | ||
20 | In the future, there will be all sorts of media types you can enable, | |
ffbf9c8b | 21 | but in the meanwhile there are six additional media types: video, audio, |
9650aa39 | 22 | raw image, ASCII art, STL/3D models, PDF and Document. |
9bc2fc6c CAW |
23 | |
24 | First, you should probably read ":doc:`configuration`" to make sure | |
9650aa39 | 25 | you know how to modify the MediaGoblin config file. |
9bc2fc6c | 26 | |
d34757dc JW |
27 | Enabling Media Types |
28 | ==================== | |
29 | ||
91bee92e RE |
30 | .. note:: |
31 | Media types are now plugins | |
32 | ||
f5e48d9e | 33 | Media types are enabled in your MediaGoblin configuration file. |
d34757dc | 34 | |
3a1fb089 BS |
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. | |
d34757dc | 38 | |
91bee92e | 39 | To enable a media type, add the the media type under the ``[plugins]`` section |
f5e48d9e | 40 | in you ``mediagoblin.ini``. For example, if your system supported image |
91bee92e | 41 | and video media types, then it would look like this:: |
d34757dc | 42 | |
91bee92e RE |
43 | [plugins] |
44 | [[mediagoblin.media_types.image]] | |
45 | [[mediagoblin.media_types.video]] | |
d34757dc | 46 | |
3a1fb089 BS |
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:: | |
9d5cd0b9 | 50 | |
3a1fb089 BS |
51 | sudo su mediagoblin --shell=/bin/bash |
52 | $ cd /srv/mediagoblin.example.org/mediagoblin | |
53 | ||
54 | Now run dbupdate:: | |
55 | ||
56 | $ ./bin/gmg dbupdate | |
9d5cd0b9 CAW |
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 | ||
d34757dc JW |
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 | ||
63b5959f LD |
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 | ||
d34757dc | 84 | |
3a1fb089 | 85 | Audio |
9bc2fc6c CAW |
86 | ===== |
87 | ||
3a1fb089 BS |
88 | To enable audio, install the GStreamer and python-gstreamer bindings (as well |
89 | as whatever GStreamer plugins you want, good/bad/ugly): | |
9bc2fc6c | 90 | |
3a8b18f8 JW |
91 | .. code-block:: bash |
92 | ||
3a1fb089 BS |
93 | # Debian and co. |
94 | sudo apt install python3-gst-1.0 gstreamer1.0-plugins-{base,bad,good,ugly} \ | |
95 | gstreamer1.0-libav | |
5ef7ab08 | 96 | |
3a1fb089 BS |
97 | # Fedora and co. |
98 | sudo dnf install gstreamer1-plugins-{base,bad-free,good,ugly-free} | |
3a8b18f8 | 99 | |
3a1fb089 BS |
100 | Add ``[[mediagoblin.media_types.audio]]`` under the ``[plugins]`` section in your |
101 | ``mediagoblin.ini`` and update MediaGoblin:: | |
9bc2fc6c | 102 | |
3a1fb089 | 103 | $ ./bin/gmg dbupdate |
7798f911 | 104 | |
3a1fb089 BS |
105 | Restart MediaGoblin (and Celery if applicable). You should now be able to upload |
106 | and listen to audio files! | |
efd69313 | 107 | |
5224d700 BS |
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 | ||
efd69313 | 122 | |
3a1fb089 | 123 | Video |
d34757dc JW |
124 | ===== |
125 | ||
3a1fb089 BS |
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): | |
d34757dc | 129 | |
3a1fb089 BS |
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 | |
d34757dc | 136 | |
34a85313 | 137 | .. note:: |
97dcfe37 | 138 | |
3a1fb089 BS |
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. | |
5ef7ab08 | 144 | |
3a1fb089 | 145 | Run:: |
3a8b18f8 | 146 | |
3a1fb089 BS |
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. | |
3fe3b222 | 151 | |
5224d700 BS |
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`". | |
5ef7ab08 | 155 | |
5224d700 BS |
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. | |
d34757dc | 159 | |
9308959b BS |
160 | Configuring video |
161 | ----------------- | |
162 | ||
163 | ``available_resolutions`` | |
164 | The list of resolutions that the video should be transcoded to, in the order | |
165 | of transcoding. Choose among ``144p``, ``240p``, ``360p``, ``480p``, ``720p`` | |
166 | and ``1080p``. The default is ``480p,360p,720p``. | |
167 | ||
168 | ``default_resolution`` | |
169 | This is the initial resolution used by the video player. The default is | |
170 | ``480p``. For example:: | |
171 | ||
172 | [[mediagoblin.media_types.video]] | |
173 | available_resolutions = 144p,240p | |
174 | default_resolution = 144p | |
175 | ||
d34757dc | 176 | |
ffbf9c8b OHO |
177 | Raw image |
178 | ========= | |
179 | ||
3a1fb089 | 180 | To enable raw image you need to install pyexiv2:: |
ffbf9c8b | 181 | |
3a1fb089 BS |
182 | # Debian and co. |
183 | sudo apt install python3-pyexiv2 | |
ffbf9c8b OHO |
184 | |
185 | Add ``[[mediagoblin.media_types.raw_image]]`` under the ``[plugins]`` | |
f5e48d9e | 186 | section in your ``mediagoblin.ini`` and restart MediaGoblin. |
ffbf9c8b | 187 | |
3a1fb089 | 188 | Run:: |
ffbf9c8b | 189 | |
3a1fb089 | 190 | $ ./bin/gmg dbupdate |
ffbf9c8b | 191 | |
3a1fb089 BS |
192 | Restart MediaGoblin (and Celery if applicable). Now you should be able to submit |
193 | raw images, and MediaGoblin should extract the JPEG preview from them. | |
ffbf9c8b OHO |
194 | |
195 | ||
9650aa39 | 196 | ASCII art |
efd69313 CAW |
197 | ========= |
198 | ||
9650aa39 | 199 | To enable ASCII art support, first install the |
efd69313 | 200 | `chardet <http://pypi.python.org/pypi/chardet>`_ |
3a1fb089 | 201 | library, which is necessary for creating thumbnails of ASCII art:: |
3a8b18f8 | 202 | |
3a1fb089 | 203 | $ ./bin/easy_install chardet |
efd69313 CAW |
204 | |
205 | ||
f5e48d9e | 206 | Next, modify your ``mediagoblin.ini``. In the ``[plugins]`` section, add |
91bee92e | 207 | ``[[mediagoblin.media_types.ascii]]``. |
efd69313 | 208 | |
3a1fb089 | 209 | Run:: |
3fe3b222 | 210 | |
3a1fb089 | 211 | $ ./bin/gmg dbupdate |
5ef7ab08 | 212 | |
3a1fb089 BS |
213 | Restart MediaGoblin (and Celery if applicable). Now any .txt file you uploaded |
214 | will be processed as ASCII art! | |
5ef7ab08 CAW |
215 | |
216 | ||
9650aa39 | 217 | STL / 3D model support |
5ef7ab08 CAW |
218 | ====================== |
219 | ||
9650aa39 BS |
220 | To enable the "STL" 3D model support plugin, first make sure you have |
221 | a recent `Blender <http://blender.org>`_ installed and available on | |
5ef7ab08 CAW |
222 | your execution path. This feature has been tested with Blender 2.63. |
223 | It may work on some earlier versions, but that is not guaranteed (and | |
224 | is surely not to work prior to Blender 2.5X). | |
225 | ||
91bee92e | 226 | Add ``[[mediagoblin.media_types.stl]]`` under the ``[plugins]`` section in your |
f5e48d9e | 227 | ``mediagoblin.ini`` and restart MediaGoblin. |
5ef7ab08 | 228 | |
3a1fb089 | 229 | Run:: |
3a8b18f8 | 230 | |
3a1fb089 | 231 | $ ./bin/gmg dbupdate |
3fe3b222 | 232 | |
3a1fb089 BS |
233 | Restart MediaGoblin (and Celery if applicable). You should now be able to upload |
234 | .obj and .stl files and MediaGoblin will be able to present them to your wide | |
235 | audience of admirers! | |
5ef7ab08 | 236 | |
a80ebf3b AL |
237 | |
238 | PDF and Document | |
239 | ================ | |
240 | ||
376dcbb4 AL |
241 | To enable the "PDF and Document" support plugin, you need: |
242 | ||
9650aa39 | 243 | 1. pdftocairo and pdfinfo for PDF only support. |
376dcbb4 | 244 | |
9650aa39 | 245 | 2. unoconv with headless support to support converting LibreOffice supported |
376dcbb4 AL |
246 | documents as well, such as doc/ppt/xls/odf/odg/odp and more. |
247 | For the full list see mediagoblin/media_types/pdf/processing.py, | |
248 | unoconv_supported. | |
249 | ||
250 | All executables must be on your execution path. | |
a80ebf3b | 251 | |
3a1fb089 | 252 | To install this on Fedora:: |
a80ebf3b | 253 | |
3a1fb089 | 254 | sudo dnf install poppler-utils unoconv libreoffice-headless |
a80ebf3b | 255 | |
9650aa39 | 256 | Note: You can leave out unoconv and libreoffice-headless if you want only PDF |
376dcbb4 AL |
257 | support. This will result in a much smaller list of dependencies. |
258 | ||
3a1fb089 | 259 | pdf.js relies on git submodules, so be sure you have fetched them:: |
a80ebf3b | 260 | |
3a1fb089 BS |
261 | $ git submodule init |
262 | $ git submodule update | |
a80ebf3b AL |
263 | |
264 | This feature has been tested on Fedora with: | |
265 | poppler-utils-0.20.2-9.fc18.x86_64 | |
266 | unoconv-0.5-2.fc18.noarch | |
267 | libreoffice-headless-3.6.5.2-8.fc18.x86_64 | |
268 | ||
269 | It may work on some earlier versions, but that is not guaranteed. | |
270 | ||
91bee92e | 271 | Add ``[[mediagoblin.media_types.pdf]]`` under the ``[plugins]`` section in your |
f5e48d9e | 272 | ``mediagoblin.ini`` and restart MediaGoblin. |
a80ebf3b | 273 | |
3a1fb089 | 274 | Run:: |
a80ebf3b | 275 | |
3a1fb089 | 276 | $ ./bin/gmg dbupdate |
a80ebf3b AL |
277 | |
278 | ||
b7d854bf CAW |
279 | Blog (HIGHLY EXPERIMENTAL) |
280 | ========================== | |
281 | ||
282 | MediaGoblin has a blog media type, which you might notice by looking | |
283 | through the docs! However, it is *highly experimental*. We have not | |
284 | security reviewed this, and it acts in a way that is not like normal | |
9650aa39 | 285 | blogs (the blog posts are themselves media types!). |
b7d854bf | 286 | |
2352f7c8 CAW |
287 | So you can play with this, but it is not necessarily recommended yet |
288 | for production use! :) |