What is Linterna Mágica?

What is Linterna Mágica?

Linterna Mágica listen
	      pronounciation 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 <object> tag that is playable by browser video plugin. The program is named after an early version of a projection apparatus - Laterna Magica. The name was taken by another project, so the Spanish translation is used now.

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 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 <object> 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.

Who made Linterna Mágica?

Original idea and programming:
Ivaylo Valkov <ivaylo@e-valkov.org>
Anton Katsarov <anton@katsarov.org>

Future releases

The last stable release of Linterna Mágica is from 2014. There are major changes in browsers in recent years that currently prevent video playback. The video URL extraction logic potentially works on most websites, but the only way to watch the video is to download it and play it outside of the browser. With the situation at hand, unfortunately most users should not be encouraged to rely on Linterna Mágica. More information is available in the text below.

Linterna Mágica has issues and limitations related to that the code is running in the same code context as the web page it examines. This is a hostile environment - a website with its own agenda, JavaScript code, and design (Cascading Style Sheets). This causes issues, ugly and complex work-arounds - Linterna Mágica not working at all, broken interface. Sometimes the entire browser used to hang because of Linterna Mágica trying to parse a web page JavaScript code as text, when that code was too big. This caused major usability issues, prevented sane work-arounds and stalled development and inclusion of new features.

The current approach, running the code in the same code context as the web page is a dead end - the work arounds for bug fixing became ugly and hard to implement at all sometimes. The code is becoming hard to maintain for the long term and it is becoming bad software design.

The user script (user code injection) approach reached the limit of its technical possibilities as I see it, for the software Linterna Mágica became and the desired direction for evolution in a software freedom respecting manner. The code must be migrated or possibly programmed from the ground up as a browser extension, which has a lot of differences technically (the main "flow/loop" of the logic) than userscripts.

Additionally in the last few years browsers are going under a lot of changes and some of the components required by Linterna Mágica were dropped out of them. For example NPAPI which allowed browsers to load external plugins, such as video players, was removed. There is video support in HTML5, but this by itself requires (major) redesign. Mozilla Firefox (and fully free software browsers based on it) had about three major extension API redesigns in a short period of time. This also led to changes in Greasemonkey (the extension loading Linterna Mágica into the browser).

Linterna Mágica needs a major redesign, but there are trade offs that depend on the approach taken. And the choices are not many. For quite some time an idea is forming how to overcome the technical obstacles and open some room for new features. With the migration of most browsers to WebExtensions as an API for extension development there seems to be a common way to find a solution.

I have ideas what might fix the issues, but they require time to study the documentation, implement, experiment and test. Currently I am on the phase of reading documentation about possible implementations. My schedule is very dynamic and I cannot always spare time. It will quite take me some time.

If you can help in any way, do not hesitate to contact me.

Crowd funding T-shirts campaign – March 2014

Since there were questions about the campaign, the point and why this way, we decided to add the answers and the explanation here as well.

The campaign?

We are running crowd funding campaign for Linterna Mágica T-Shirts, that would help development and spread the word about us.

Our goal is at least 20 preorders for the prints to be produced and delivered. The campaign ends at 20th of March.

If the campaign is successful everyone who ordered a T-shirt will get one. The money will be split between me (the developer), Anton (the designer) and the campaign site. If the required minimal amount of preorders (20) is not reached, the campaign fails, the people gets their money back and that's it.

Why this indirect way for donations?

The direct ways were always on the website, but donations for Linterna Mágica are rare. We had one big donation from ThinkPenguin (Chris, thanks again!) few years ago. Only few people donated (you know who you are, thanks!) over the years. Last year we had a survey in which very few decided to participate. It showed that we have a problem in the donation area.

This is a zero-cost-entry campaign for us... well I've spent one night with 4 hours of sleep, but still. :) The campaign on the T-shirts themselves could reach people (offline) whom we cannot, because we don't walk on the same path over the Internet. And since donations are rare, we are trying this more dynamic approach with additional benefit for those who are wondering should they make a financial contribution.

I would love it if people donated more, because I would be able to spend more time on Linterna Mágica and they would get better Linterna Mágica. Work on LM cannot be compared with anything for hire, unfortunately I can work on it in my "spare" time. That's the cruel reality. :)

The result?

Thanks to a Reddit (and probably Linterna Mágica as well) user, we met our goal at the second or the third day of the campaign. Although only the base goal was reached the campaign is successful.

We decided to use the money from the T-shirts campaign and the donations relevant to it, to fund a new interesting and exiting project related to free software. Stay tuned!

The T-shirts?


Supported extensions

Linterna Mágica is tested with:

Supported browsers

Linterna Mágica is tested with:

  • Epiphany

    Epiphany versions older than 2.30 might have problems with Greasemonkey.

  • Free software versions of Firefox

    Free software versions of Firefox that support the Greasemonkey extension should work. Only GNU IceCat, Web Browser/ABrowser and Iceweasel are tested.

  • Midori
  • Iceape/Seamonkey
  • Chromium

Supported video plugins

Plugins that can handle "video/flv" and "video/mp4" should work right away. Some plugins provide an API which is used in Linterna Mágica to support web controls, but this will require modifications to the code, if the plugin is not listed as supported. There is a configuration option to switch between controls provided by the plugin and Linterna Mágica.

These plugins are known to work:

  • Totem plugin.

    Versions older and equal to 2.30 does not have full API support for web controls. Newer versions of Totem have been patched (#623790, #618929) and should work.

  • VLC plugin
  • gecko-mediaplayer plugin

    Note: Have in mind that gecko-mediaplayer depends on mplayer for playback. Mplayer is free software by itself, but it can load and recommends binary only codecs. The completely free (as in freedom) distribution of GNU/Linux, Trisquel provides clean version of mplayer.

  • Xine plugin

Probably these plugins are available in your GNU/Linux distribution as a package.

You can test your browser plugins and the installation of Linterna Mágica at the test page.

Supported websites

Linterna Mágica is programmed in such a way that it might work (and it does) with web sites not specifically tested and supported. This is achieved by regular expressions, patterns and similarities between video sharing and posting sites. The main idea is that very little should be needed to support a new site - few changes in a regular expression, adding an address from where the clip should be extracted and so on. By default Linterna Mágica runs on every site, but that might not be suitable for you. Read the documentation to find out how to stop this.

Some of the most popular video sharing sites are known to work:

  • youtube.com
  • vimeo.com
  • metacafe.com
  • dailymotion.com
  • blib.tv
  • video.google.com (video.google.*)
  • vbox7.bg (Bulgarian)

There are more than 30 web sites, found with random web searches that are known to work. Web sites that have the video link somewhere in the HTML/JavaScript code, or it can be extracted through some ID, should work. If that is not the case, probably it will be very easy to support them. See the WEBSITES file in Linterna Mágica source tarball for all known working sites and more information.

Not supported websites

Websites that use RTMP to transfer the video are not supported.

For the moment flash objects embedded in remote web sites do not work. Since version 0.0.9 some remote objects are detected and a link to the web page of the video is provided.

Linterna Mágica is not working with specific browser or plugin or operating system. Is it possible to support it?

Only free software will be supported. Explicit support for non-free software will not be provided. If Linterna Mágica is working with non-free software you must be very "lucky". Yes, that is sarcasm!


Linterna Mágica is free software. You can distribute it and or modify it under the terms of the GNU GPL version 3 or later. You can see the license in the COPYING file in Linterna Mágica source tarball or at the GNU project web page: https://www.gnu.org/licenses/gpl.html.

All the supported browsers and plugins are distributed under a free software license.


Stable releases

Older releases

Release date:
03 March 2014
  • Another YouTube bug-fix release. Because we love YouTube so much. ;) Fixed false positive encrypted signatures detection.
Release date:
28 February 2014
  • Fixed YouTube playlists auto and shuffle playback (if YouTube buttons are present)
  • Fixed YouTube playlists sidebar displacement
Release date:
20 February 2014
  • Fixed Kickstarter.com support.
  • In attempt to fix issues with Firefox, from now on Linterna Mágica have to be started manualy by a click of a button. Exceptions are YouTube, Dailymotion and Vimeo. More can be added. Read the docs. (#39111, #41577, #39320).
Release date:
25 January 2014
  • YouTube is using AJAX (background requests) for the entire navigation around the site. Linterna Mágica forces foreground requests all around YouTube, so it can work.
  • Faster loading in YouTube - from few milliseconds to few seconds.
  • Automatic playback of next song when clip is unavailable in YouTube playlists.
  • Added experimental feature to rewrites YouTube video urls to https when a page is requested over https. Should work around mixed content warnings in Firefox. See also bug 39726 (Bug #39726).
  • A simple one time switch from website HTML5 players to Linterna Mágica is brought back. By default everything is replaced. This option is available via custom configuration. Fixes bug 40542 (Bug #40542).
  • Added support for playback in video.repubblica.it without flash plugin. Fixes bug 40627 (Bug #40627).
Release date:
10 November 2013
  • Fixed bug 39313 (Bug #39319)
  • Added format configuration option. It can select preferred formats (webm/h264/mpg etc.) See the docs.
  • Improved quality selection. It is now possible to quality to 360p, 480p etc. etc.
  • Added support for YouTube playlists - LM can now play the whole list (shuffle and ordered).
  • Fixed YoUTube glitches.
  • Switching between HTMl5, Flash and Linterna Magica is derecated. The default behaviour is to replace the default player of the website.
  • Scriptish, Tampermonkey, Chromium and Iceape are considered officially supported.
  • Fixed browser history navigation. Because of this fix, the updates checker now sends referrer to linternamagica.org. Sorry, there is no way around it. (Bug #38861)
  • Fixed support for Dailymotion (Bug #39564)
  • A warning is displayed for video pages serving mixed content. (Bug #39726)
  • Fixed displacement in Friendica node karl.marx.pm (Bug #39575)
  • Fixed Vimeo support. (Bug #40442)
  • A warning is displayed for YouTube clips with encrypted signatures. Those clips cannot be played. (Bug #39402)
  • Added support for videolectures.net (Bug #38400)
  • Added support for xhamster (Bug #38837)

Unstable releases

Git daily builds
Release date:
Every day after 00:30 (EET and EEST timezones)
These versions are automatically build from the Git repository and contain the latest fixes and features. Only userscripts are provided.

The daily builds are not stable!!! Even the builds from the stable branch might be considered unstable. If possible use a stable version from the the list of stable releases.

When enough issues are fixed in the stable branch a new bug-fix release is available (for example 0.0.9-4). This branch is stable enough to be used, but If possible, use a stable version.

The version in the master branch is the one under active development.

If you decide to use unstable version, it is recommended to disable any other version of Linterna Mágica that is installed. If you can't disable userscripts with your current version of the Greasemonkey extension (or the browser implementation for userscripts), then uninstall any other version. These builds do not check for updates, even if configured to do so.

Source from Git

You can download the source code of any version from the Git repository at our project page at Savannah.

If you want the latest version in development, use:

    git clone git://git.sv.gnu.org/linterna-magica.git linterna-magica-master

The Git master version never checks for updates.

If you want the latest code for specific version (in this case 0.0.9), use:

    git clone --branch=0.0.9 git://git.sv.nongnu.org/linterna-magica.git linterna-magica-stable-0.0.9

Each version under branches has the latest fixes for the branch. The version of Linterna Mágica is set to the version of the latest released (or to be released) bug-fix version. This is the latest, not the first released version from the branch.

If you want specific bug-fix release (in this case 0.0.9-3), use:

    git clone git://git.sv.gnu.org/linterna-magica.git linterna-magica-0.0.9-3
    cd linterna-magica-0.0.9-3 
    git checkout 0.0.9-3

The versions under tags are the stable releases.


Linterna Mágica user config
Keep your configuration in separate userscript file. This way your preferences will stay intact when new version is installed. This works with builds from the master Git branch and versions above 0.0.10. Read the documentation to find out how to use this script.

The following link is not an actual version. It is meant to test crawlers and robots handling by Awstats on Savannah. This is used only for the purpose of download statistics. Please do not click this link. Normally this text and the links should not be visible in your browser, unless you had disabled CSS.

Fake version Fake version



Test Linterna Mágica

You can test your browser plugins and the installation of Linterna Mágica at the test page.

Report bugs

You can report bugs at the project's page at Savannah. Use the Bugs tracker, the "Tech Support Manager"/"Support" is now deprecated.

Mailing lists

The mailing lists are available in the Mailing lists section at our Savannah project page.

Jabber and IRC

We have two official chat rooms.

A bot (lm-jabber2irc) relays messages between the rooms, so you can join either. The main developer's nick is Dreamer in Jabber and thedreamer in IRC.


Linterna Mágica is free software and can be downloaded, shared and modified freely. It respects your software freedom by allowing you to watch videos on the web entirely with free software. If you like it and find it useful, then consider making a donation. Enough donations will ensure faster bug fixes and new features, as I would be able to take some time off work and spend my energy on Linterna Mágica.

You can donate via PayPal. If you already made a donation, thank you!

ThinkPenguin had sponsored Linterna Mágica. Thanks!

A special thanks goes to ThinkPenguin for making the first substantial donation to the project in the amount of €100.


Older announcements

04 April 2016

It has been quite quiet here for a long time. Unfortunately our plan for a side project related to free software supported by the money from the T-shirts campaign didn't go live.

This project is on a great hold. It has taken a lot of my spare time over the years and did not met some of the goals that I had for it. At the moment my spare time is dedicated to a real life escape room project in Varna Bulgaria.

22 March 2014

Our campaign is over. It was a success!

We decided to use the money from the T-shirts and the donations relevant to the campaign, to fund a new interesting and exiting project related to free software.

Stay tuned!

03 March 2014

  • New bug-fix release 1.22 is available for download.

28 February 2014

  • New bug-fix release 1.21 is available for download.
  • We have a running campaign for T-shirts. Twenty (20) preorders are needed until 20th of March for the campaign to succeed and the T-shirts to be printed and delivered. Buying a T-shirt helps development and spread the word about Linterna Mágica!

20 February 2014

  • New stable release 1.20 is available for download.
  • Litecoin and Bitcoin are accepted for donations.

25 January 2014

  • New stable release 1.10 is available for download.
  • Updated version of the helper script (Utilities section) for configuration. There are issues in Firefox with the older version. Use the new version otherwise it might not work.

10 November 2013

  • New stable release 1.0 is available for download.
  • The versioning scheme is changed - major_version.minor_version. Stable releases have minor versions divisable by 10 (10, 20, 30) and 0. Bug fix releases have minor versions non-divisable by 10 (1..9, 11..19, 21..29 etc). The major version will increase with significant changes.
  • Since Identi.ca migration to pump.io we do not have microblogging group. There is no permanent solution yet, but the microblog link points to my personal account. Meanwhile checkout our IRC and Jabber rooms.

01 November 2013

02 September 2013

25 August 2013

  • The source code repository of the project will be migrated from SVN to Git soon.
  • The website source code repository will be migrated from CVS to Git soon.
  • The website domain will change from linterna-magica.nongnu.org to linternamagica.org soon.

1 April 2013

  • Bug-fix release 0.0.13-2 is available for download.

17 February 2013

  • The survey is now over. The final results are available.
  • Bug-fix release 0.0.13-1 is available for download.