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 JW |
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 | ||
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 | |
9d5cd0b9 CAW |
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 | ||
d34757dc JW |
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 | ||
63b5959f LD |
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 | ||
d34757dc | 77 | |
9bc2fc6c CAW |
78 | Video |
79 | ===== | |
80 | ||
9650aa39 BS |
81 | To enable video, first install GStreamer and the python-gstreamer |
82 | bindings (as well as whatever GStreamer extensions you want, | |
3a8b18f8 | 83 | good/bad/ugly). On Debianoid systems |
9bc2fc6c | 84 | |
3a8b18f8 JW |
85 | .. code-block:: bash |
86 | ||
919cd2fd BB |
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 \ | |
eade529e BB |
94 | gstreamer1.0-libav \ |
95 | python-gst-1.0 | |
582958e3 | 96 | |
9bc2fc6c | 97 | |
91bee92e | 98 | Add ``[[mediagoblin.media_types.video]]`` under the ``[plugins]`` section in |
f5e48d9e | 99 | your ``mediagoblin.ini`` and restart MediaGoblin. |
5ef7ab08 | 100 | |
3a8b18f8 JW |
101 | Run |
102 | ||
103 | .. code-block:: bash | |
3fe3b222 | 104 | |
5ef7ab08 CAW |
105 | ./bin/gmg dbupdate |
106 | ||
9650aa39 | 107 | Now you should be able to submit videos, and MediaGoblin should |
9bc2fc6c CAW |
108 | transcode them. |
109 | ||
7798f911 WKG |
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. | |
efd69313 CAW |
116 | |
117 | ||
d34757dc JW |
118 | Audio |
119 | ===== | |
120 | ||
9650aa39 BS |
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 | |
d34757dc JW |
123 | also needed for the audio spectrograms. |
124 | To install these on Debianoid systems, run:: | |
125 | ||
8af91cea | 126 | sudo apt-get install python-gst-1.0 gstreamer1.0-plugins-{base,bad,good,ugly} \ |
94a5d6a8 | 127 | gstreamer1.0-libav python-numpy python-scipy libsndfile1-dev libasound2-dev |
d34757dc | 128 | |
34a85313 | 129 | .. note:: |
8518e95e | 130 | scikits.audiolab will display a warning every time it's imported if you do |
34a85313 | 131 | not compile it with alsa support. Alsa support is not necessary for the GNU |
8af91cea | 132 | MediaGoblin application. |
34a85313 | 133 | |
97dcfe37 | 134 | If you're running Python 2, install ``scikits.audiolab`` for the spectrograms:: |
d34757dc | 135 | |
2b487fc1 J |
136 | .. code-block:: bash |
137 | ||
138 | ./bin/pip install numpy==1.9.1 | |
139 | ./bin/pip install scikits.audiolab==0.10.2 | |
d34757dc | 140 | |
2b487fc1 J |
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) | |
97dcfe37 | 143 | |
91bee92e | 144 | Add ``[[mediagoblin.media_types.audio]]`` under the ``[plugins]`` section in your |
f5e48d9e | 145 | ``mediagoblin.ini`` and restart MediaGoblin. |
5ef7ab08 | 146 | |
3a8b18f8 JW |
147 | Run |
148 | ||
149 | .. code-block:: bash | |
3fe3b222 | 150 | |
5ef7ab08 CAW |
151 | ./bin/gmg dbupdate |
152 | ||
153 | You should now be able to upload and listen to audio files! | |
d34757dc JW |
154 | |
155 | ||
ffbf9c8b OHO |
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]`` | |
f5e48d9e | 166 | section in your ``mediagoblin.ini`` and restart MediaGoblin. |
ffbf9c8b OHO |
167 | |
168 | Run | |
169 | ||
170 | .. code-block:: bash | |
171 | ||
172 | ./bin/gmg dbupdate | |
173 | ||
9650aa39 | 174 | Now you should be able to submit raw images, and MediaGoblin should |
ffbf9c8b OHO |
175 | extract the JPEG preview from them. |
176 | ||
177 | ||
9650aa39 | 178 | ASCII art |
efd69313 CAW |
179 | ========= |
180 | ||
9650aa39 | 181 | To enable ASCII art support, first install the |
efd69313 | 182 | `chardet <http://pypi.python.org/pypi/chardet>`_ |
9650aa39 | 183 | library, which is necessary for creating thumbnails of ASCII art |
3a8b18f8 JW |
184 | |
185 | .. code-block:: bash | |
efd69313 CAW |
186 | |
187 | ./bin/easy_install chardet | |
188 | ||
189 | ||
f5e48d9e | 190 | Next, modify your ``mediagoblin.ini``. In the ``[plugins]`` section, add |
91bee92e | 191 | ``[[mediagoblin.media_types.ascii]]``. |
efd69313 | 192 | |
3a8b18f8 JW |
193 | Run |
194 | ||
195 | .. code-block:: bash | |
3fe3b222 | 196 | |
5ef7ab08 CAW |
197 | ./bin/gmg dbupdate |
198 | ||
9650aa39 | 199 | Now any .txt file you uploaded will be processed as ASCII art! |
5ef7ab08 CAW |
200 | |
201 | ||
9650aa39 | 202 | STL / 3D model support |
5ef7ab08 CAW |
203 | ====================== |
204 | ||
9650aa39 BS |
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 | |
5ef7ab08 CAW |
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 | ||
91bee92e | 211 | Add ``[[mediagoblin.media_types.stl]]`` under the ``[plugins]`` section in your |
f5e48d9e | 212 | ``mediagoblin.ini`` and restart MediaGoblin. |
5ef7ab08 | 213 | |
3a8b18f8 JW |
214 | Run |
215 | ||
216 | .. code-block:: bash | |
3fe3b222 | 217 | |
5ef7ab08 CAW |
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! | |
a80ebf3b AL |
222 | |
223 | PDF and Document | |
224 | ================ | |
225 | ||
376dcbb4 AL |
226 | To enable the "PDF and Document" support plugin, you need: |
227 | ||
9650aa39 | 228 | 1. pdftocairo and pdfinfo for PDF only support. |
376dcbb4 | 229 | |
9650aa39 | 230 | 2. unoconv with headless support to support converting LibreOffice supported |
376dcbb4 AL |
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. | |
a80ebf3b AL |
236 | |
237 | To install this on Fedora: | |
238 | ||
239 | .. code-block:: bash | |
240 | ||
3606316e | 241 | sudo yum install -y poppler-utils unoconv libreoffice-headless |
a80ebf3b | 242 | |
9650aa39 | 243 | Note: You can leave out unoconv and libreoffice-headless if you want only PDF |
376dcbb4 AL |
244 | support. This will result in a much smaller list of dependencies. |
245 | ||
a80ebf3b AL |
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 | ||
91bee92e | 260 | Add ``[[mediagoblin.media_types.pdf]]`` under the ``[plugins]`` section in your |
f5e48d9e | 261 | ``mediagoblin.ini`` and restart MediaGoblin. |
a80ebf3b AL |
262 | |
263 | Run | |
264 | ||
265 | .. code-block:: bash | |
266 | ||
267 | ./bin/gmg dbupdate | |
268 | ||
269 | ||
b7d854bf CAW |
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 | |
9650aa39 | 276 | blogs (the blog posts are themselves media types!). |
b7d854bf | 277 | |
2352f7c8 CAW |
278 | So you can play with this, but it is not necessarily recommended yet |
279 | for production use! :) |