Commit | Line | Data |
---|---|---|
473a4431 CAW |
1 | .. MediaGoblin Documentation |
2 | ||
ffbf9c8b | 3 | Written in 2011, 2012, 2014 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 OHO |
21 | but in the meanwhile there are six additional media types: video, audio, |
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 | |
25 | you know how to modify the mediagoblin config file. | |
26 | ||
d34757dc JW |
27 | Enabling Media Types |
28 | ==================== | |
29 | ||
91bee92e RE |
30 | .. note:: |
31 | Media types are now plugins | |
32 | ||
d34757dc JW |
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 | ||
91bee92e RE |
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:: | |
d34757dc | 45 | |
91bee92e RE |
46 | [plugins] |
47 | [[mediagoblin.media_types.image]] | |
48 | [[mediagoblin.media_types.video]] | |
d34757dc | 49 | |
9d5cd0b9 CAW |
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 | ||
d34757dc JW |
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 | ||
9bc2fc6c CAW |
73 | Video |
74 | ===== | |
75 | ||
76 | To enable video, first install gstreamer and the python-gstreamer | |
77 | bindings (as well as whatever gstremaer extensions you want, | |
3a8b18f8 | 78 | good/bad/ugly). On Debianoid systems |
9bc2fc6c | 79 | |
3a8b18f8 JW |
80 | .. code-block:: bash |
81 | ||
919cd2fd BB |
82 | sudo apt-get install python-gi python3-gi \ |
83 | gstreamer1.0-tools \ | |
84 | gir1.2-gstreamer-1.0 \ | |
85 | gir1.2-gst-plugins-base-1.0 \ | |
86 | gstreamer1.0-plugins-good \ | |
87 | gstreamer1.0-plugins-ugly \ | |
88 | gstreamer1.0-plugins-bad \ | |
89 | gstreamer1.0-libav | |
582958e3 | 90 | |
9bc2fc6c | 91 | |
91bee92e RE |
92 | Add ``[[mediagoblin.media_types.video]]`` under the ``[plugins]`` section in |
93 | your ``mediagoblin_local.ini`` and restart MediaGoblin. | |
5ef7ab08 | 94 | |
3a8b18f8 JW |
95 | Run |
96 | ||
97 | .. code-block:: bash | |
3fe3b222 | 98 | |
5ef7ab08 CAW |
99 | ./bin/gmg dbupdate |
100 | ||
9bc2fc6c CAW |
101 | Now you should be able to submit videos, and mediagoblin should |
102 | transcode them. | |
103 | ||
7798f911 WKG |
104 | .. note:: |
105 | ||
106 | You almost certainly want to separate Celery from the normal | |
107 | paste process or your users will probably find that their connections | |
108 | time out as the video transcodes. To set that up, check out the | |
109 | ":doc:`production-deployments`" section of this manual. | |
efd69313 CAW |
110 | |
111 | ||
d34757dc JW |
112 | Audio |
113 | ===== | |
114 | ||
115 | To enable audio, install the gstreamer and python-gstreamer bindings (as well | |
116 | as whatever gstreamer plugins you want, good/bad/ugly), scipy and numpy are | |
117 | also needed for the audio spectrograms. | |
118 | To install these on Debianoid systems, run:: | |
119 | ||
120 | sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \ | |
121 | gstreamer0.10-ffmpeg python-numpy python-scipy | |
122 | ||
123 | The ``scikits.audiolab`` package you will install in the next step depends on the | |
124 | ``libsndfile1-dev`` package, so we should install it. | |
3a8b18f8 JW |
125 | On Debianoid systems, run |
126 | ||
127 | .. code-block:: bash | |
d34757dc JW |
128 | |
129 | sudo apt-get install libsndfile1-dev | |
130 | ||
34a85313 | 131 | .. note:: |
8518e95e | 132 | scikits.audiolab will display a warning every time it's imported if you do |
34a85313 | 133 | not compile it with alsa support. Alsa support is not necessary for the GNU |
8518e95e JW |
134 | MediaGoblin application but if you do not wish the alsa warnings from |
135 | audiolab you should also install ``libasound2-dev`` before installing | |
136 | scikits.audiolab. | |
34a85313 | 137 | |
d34757dc JW |
138 | Then install ``scikits.audiolab`` for the spectrograms:: |
139 | ||
140 | ./bin/pip install scikits.audiolab | |
141 | ||
91bee92e | 142 | Add ``[[mediagoblin.media_types.audio]]`` under the ``[plugins]`` section in your |
5ef7ab08 CAW |
143 | ``mediagoblin_local.ini`` and restart MediaGoblin. |
144 | ||
3a8b18f8 JW |
145 | Run |
146 | ||
147 | .. code-block:: bash | |
3fe3b222 | 148 | |
5ef7ab08 CAW |
149 | ./bin/gmg dbupdate |
150 | ||
151 | You should now be able to upload and listen to audio files! | |
d34757dc JW |
152 | |
153 | ||
ffbf9c8b OHO |
154 | Raw image |
155 | ========= | |
156 | ||
157 | To enable raw image you need to install pyexiv2. On Debianoid systems | |
158 | ||
159 | .. code-block:: bash | |
160 | ||
161 | sudo apt-get install python-pyexiv2 | |
162 | ||
163 | Add ``[[mediagoblin.media_types.raw_image]]`` under the ``[plugins]`` | |
164 | section in your ``mediagoblin_local.ini`` and restart MediaGoblin. | |
165 | ||
166 | Run | |
167 | ||
168 | .. code-block:: bash | |
169 | ||
170 | ./bin/gmg dbupdate | |
171 | ||
172 | Now you should be able to submit raw images, and mediagoblin should | |
173 | extract the JPEG preview from them. | |
174 | ||
175 | ||
efd69313 CAW |
176 | Ascii art |
177 | ========= | |
178 | ||
179 | To enable ascii art support, first install the | |
180 | `chardet <http://pypi.python.org/pypi/chardet>`_ | |
3a8b18f8 JW |
181 | library, which is necessary for creating thumbnails of ascii art |
182 | ||
183 | .. code-block:: bash | |
efd69313 CAW |
184 | |
185 | ./bin/easy_install chardet | |
186 | ||
187 | ||
188 | Next, modify (and possibly copy over from ``mediagoblin.ini``) your | |
91bee92e RE |
189 | ``mediagoblin_local.ini``. In the ``[plugins]`` section, add |
190 | ``[[mediagoblin.media_types.ascii]]``. | |
efd69313 | 191 | |
3a8b18f8 JW |
192 | Run |
193 | ||
194 | .. code-block:: bash | |
3fe3b222 | 195 | |
5ef7ab08 CAW |
196 | ./bin/gmg dbupdate |
197 | ||
efd69313 | 198 | Now any .txt file you uploaded will be processed as ascii art! |
5ef7ab08 CAW |
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 recentish `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 | ||
91bee92e | 210 | Add ``[[mediagoblin.media_types.stl]]`` under the ``[plugins]`` section in your |
919cd2fd | 211 | ``mediagoblin_local.ini`` and restart MediaGoblin. |
5ef7ab08 | 212 | |
3a8b18f8 JW |
213 | Run |
214 | ||
215 | .. code-block:: bash | |
3fe3b222 | 216 | |
5ef7ab08 CAW |
217 | ./bin/gmg dbupdate |
218 | ||
219 | You should now be able to upload .obj and .stl files and MediaGoblin | |
220 | will be able to present them to your wide audience of admirers! | |
a80ebf3b AL |
221 | |
222 | PDF and Document | |
223 | ================ | |
224 | ||
376dcbb4 AL |
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. | |
a80ebf3b AL |
235 | |
236 | To install this on Fedora: | |
237 | ||
238 | .. code-block:: bash | |
239 | ||
3606316e | 240 | sudo yum install -y poppler-utils unoconv libreoffice-headless |
a80ebf3b | 241 | |
376dcbb4 AL |
242 | Note: You can leave out unoconv and libreoffice-headless if you want only pdf |
243 | support. This will result in a much smaller list of dependencies. | |
244 | ||
a80ebf3b AL |
245 | pdf.js relies on git submodules, so be sure you have fetched them: |
246 | ||
247 | .. code-block:: bash | |
248 | ||
249 | git submodule init | |
250 | git submodule update | |
251 | ||
252 | This feature has been tested on Fedora with: | |
253 | poppler-utils-0.20.2-9.fc18.x86_64 | |
254 | unoconv-0.5-2.fc18.noarch | |
255 | libreoffice-headless-3.6.5.2-8.fc18.x86_64 | |
256 | ||
257 | It may work on some earlier versions, but that is not guaranteed. | |
258 | ||
91bee92e | 259 | Add ``[[mediagoblin.media_types.pdf]]`` under the ``[plugins]`` section in your |
919cd2fd | 260 | ``mediagoblin_local.ini`` and restart MediaGoblin. |
a80ebf3b AL |
261 | |
262 | Run | |
263 | ||
264 | .. code-block:: bash | |
265 | ||
266 | ./bin/gmg dbupdate | |
267 | ||
268 | ||
b7d854bf CAW |
269 | Blog (HIGHLY EXPERIMENTAL) |
270 | ========================== | |
271 | ||
272 | MediaGoblin has a blog media type, which you might notice by looking | |
273 | through the docs! However, it is *highly experimental*. We have not | |
274 | security reviewed this, and it acts in a way that is not like normal | |
275 | blogs (the blogposts are themselves media types!). | |
276 | ||
2352f7c8 CAW |
277 | So you can play with this, but it is not necessarily recommended yet |
278 | for production use! :) |