Linterna Mágica ***************** This manual (updated 20 February 2014) is for Linterna Mágica (version 1.20), a userscript for watching web video clips inside a browser without the proprietary flash technology. Watch video on the web in a brand new way: "You don't need a glint, the magic lantern is ignited!" Copyright (C) 2010, 2011, 2012 Ivaylo Valkov <> Copyright (C) 2013, 2014 Ivaylo Valkov <> Copyright (C) 2010 Anton Katsarov <> Permission is granted to copy, distribute and/or modify this document under the terms of either * the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version, or * the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. Copies of the licenses are included in the sections entitled "GNU General Public License" and "GNU Free Documentation License" respectively. 1 Introduction to Linterna Mágica *********************************** 1.1 What is Linterna Mágica? ============================== Linterna Mágica is "tiny" (at least it started that way) script written in JavaScript for the Greasemonkey extension. It searches web pages for flash objects with links to video clips and replaces them with tag that is playable by browser video plugin. The program is named after an early version of a projection apparatus. 1.2 Why it exists? ================== The short answer: I had spare time and was curious is it going to work. The long answer: Free software flash plugins like Gnash and Swfdec do not work well with video flash players on every site. On top of that: * Even with free software plugin you run a lot of proprietary software as ActionScript * Even the free software plugins use too much resources * Flash is proprietary technology * Flash is not a web standard * Most of the flash objects in a page contain useless stuff Playback of video clips in a browser is technically possible since the existence of the tag (around 1999; maybe even before that?!). To watch a video inside a browser the user always needs a plugin (HTML5 changes that a bit). Why it should be flash plugin? Most of the time I do not have Gnash or Swfdec installed. I do not care about flash except, sometimes for video clips. I got tired of using Bash/Perl/Python... scripts to download video clips and watch them. Linterna Mágica was born. 1.3 Who made it? ================ Original idea and programming by Ivaylo Valkov. Interface design by Anton Katsarov. 1.4 How to pronounce Linterna Mágica? ======================================== The name Linterna Mágica is in Spanish. The pronunciation in IPA is /lintˈɛrna maxˈika/. You can also find the answer to that question by playing the Ogg Vorbis file `linterna mágica - pronounce.ogg' located in the `data' directory. 2 Installation and building *************************** 2.1 Building the userscript =========================== Since version 0.0.9 of Linterna Mágica the userscript have to be build, if you have downloaded the source code tarball. If you do not want to build the script, visit Linterna Mágica's web site and download the compiled version of the script, which is ready for installation. To build the userscript you will need the following packages: `GNU make' `GNU sed' `GNU grep' `GNU bash' `GNU Coreutils' `ls', `cp', `rm', `cat', `tac', `head', `tail', `cut', `tr', `sort', `uniq', `base64', `basename', `mktemp', `test', `echo', `chmod' To build the userscript, inside a terminal change the directory to the source code directory of Linterna Mágica and type: `make' If everything went fine, at the end of the building process you should see the following message: linternamagica.user.js is ready. To remove all the generated files without the userscript, type: `make clean' To remove all the generated files and the userscript file, type: `make distclean' 2.2 Installation ================ First of all install the userscript extension for your browser and activate it. For Epiphany it is part of the Epiphany-extensions package. For GNU IceCat, Abrowser and other versions of Firefox see the Greasemonkey and/or the Scriptish web pages. For Chromium see the Tampermonkey website. Probably these extensions are available in your GNU/Linux distribution as a package. Second, install the video plugin that you prefer. If you have downloaded version of the userscript compressed with gzip or bzip2, decompress it to get a copy of the file ready for installation. 2.2.1 Installation from browser ------------------------------- Load the path where you downloaded Linterna Mágica in your browser: `file:///home/user/linterna-magica/' You can also start it from a terminal: `epiphany file:///home/user/linterna-magica/' or `abrowser file:///home/user/linterna-magica/' or `icecat file:///home/user/linterna-magica/' `iceape file:///home/user/linterna-magica/' Right-click the user script and from the menu select For Epiphany "Install userscript" For GNU IceCat and other free software versions of Firefox "View User Script Source". In the new window click the Greasemonkey "Install" button. If you are using Scriptish, choose "Install User Script…". For Midori For Midori version 0.3.0 and above select "Open Link in Bew Tab". In the new tab click "Install user script" button. Versions before 0.3.0 do not support instala do not support installation of userscripts from the browser. For Iceape (and other versions of Seamonkey) "Install User Script…" 2.2.2 Installation from terminal -------------------------------- Another option to install the userscript is to copy it from a terminal. The paths in the examples bellow might be different in your configuration and setup. For Epiphany: `cp linternamagica.user.js \ ~/.gnome2/epiphany/extensions/data/greasemonkey/linterna_magica.user.js' For GNU IceCat: `mkdir ~/.gnuzilla/icecat/profile/gm_scripts/linterna_magica/' `cp linternamagica.user.js \ ~/.gnuzilla/icecat/profile/gm_scripts/linterna_magica/linterna_magica.user.js' For other free software versions of Firefox: `mkdir ~/.mozilla/firefox/profile/gm_scripts/linterna_magica/' `cp linternamagica.user.js \ ~/.mozilla/firefox/profile/gm_scripts/linterna_magica/linterna_magica.user.js' For Midori: `mkdir ~/.local/share/midori/scripts/' `cp linternamagica.user.js \ ~/.local/share/midori/scripts/linterna_magica.user.js' For Iceape (and other versions of Seamonkey): Iceape works only with Scriptish for which there is no easy way to install scripts from a terminal. The scripts are located in `~/.mozila/seamonkey/profile/scriptsh_scripts' but for every installed script there is a definition needed in the file `~/.mozila/seamonkey/profile/scriptsh_scripts/scriptish-config.json' which does not seem simple enough to be done by hand. 3 Configuration *************** Linterna Mágica has some configuration options. The only way (for now) to configure it, is to edit the code of the userscript. 3.1 Configuration options ========================= To change the configuration of Linterna Mágica open the userscript file and look for `var linterna_magica_options'. This is a JavaScript object that keeps configuration options in "option":"value" format: var linterna_magica_options = { "debug": 0, "log_to": "web", "web_log_expand": false, "updates": "1w", "priority": "self", "manual_run": "on", "skip_manual_run": [ "youtube.com", "vimeo.com", "dailymotion.com", ], "autostart": "off", "controls": "self", "locale": "auto", "cookies": "restore", "wait_xhr": "off", "quality": "low", "format": "mp4" }; Since version 0.0.10 it is possible to keep your configuration in separate userscript file. This way your preferences will stay intact when new version is installed. The userscript with your configuration must have special structure. If you want this feature, install the file `linternamagica_user_condfig.user.js' from the `utilities' directory. To change the configuration look for `var linterna_magica_user_config'. The format is the same as for the main userscript file. Have in mind that this file is not going to be updated and you will have to add manually new options implemented in future versions, if you don't like the default ones. If an option is missing in this file, the default one provided by the main userscript will be used. Available options are: `debug' This option sets the debug level. The debug information is printed in the console. `0' Do not print anything (default) `1..5' Print debug information `log_to' Where to print the debugging information when debug is not zero. `web' Print messages in the web page (default) `console' Use the debugging console of the browser `web_log_expand' Should the web logger be automatically expanded by default `false' No (default) `true' Yes `updates' Should Linterna Mágica automatically check and notify for updates. *Note Automatic check for updates::. `