MultimediaLib

MultimediaLib is a framework for creating multimedia applications in Java that run on multiple platforms: desktop applications (Windows, Mac OS, Linux), mobile apps (iOS, Android), and web (browser, PWA). MultimediaLib mainly targets 2D graphics and animation, though support for basic 3D graphics is also provided.

MultimediaLib acts as an abstraction layer between the application and the platform's underlying resources, such as graphics, audio, input, and network access. Other frameworks use a similar approach but tend to target mobile platforms, native applications (on mobile/desktop/both), or web applications. MultimediaLib's main strength is that applications will run on all those different platforms.

MultimediaLib has been in use since all the way back to 2009. It used to support long-forgotten front-end technologies like Java Web Start and later transitioned to browser-based technologies once WebGL became widely supported, while retaining its original support for desktop applications.

Usage

The library is available from the Maven Central repository. To use it in a Maven project, add it to the dependencies section in pom.xml:

<dependency>
    <groupId>nl.colorize</groupId>
    <artifactId>multimedialib</artifactId>
    <version>2026.4</version>
</dependency>  

The library can also be used in Gradle projects:

dependencies {
    implementation "nl.colorize:multimedialib:2026.4"
}

Supported platforms

MultimediaLib provides multiple renderers, that act as the interface between the application and the underlying platform. Multiple renderer implementations are provided. This allows 99% of application code to be cross-platform, apart from a small platform-specific launcher that initializes the application with the correct renderer.

The following renderer implementations are available:

Renderer	Graphics	Platforms
Java2D renderer	2D	Windows, Mac, Linux
libGDX renderer	2D + 3D	Windows, Mac, Android, Browser
Skija renderer (Beta)	2D	Windows, Mac
HTML canvas renderer	2D	Browser, iOS, Android
Headless renderer	Headless	Testing/simulation

The current selection of renderers can be divided into different categories:

• Basic renderers that focus on portability, such as the Java2D renderer for desktop platforms and the HTML canvas renderer for browser-based applications.
• Hardware-accelerated renderers, which have superior graphics quality and performance, with the libGDX renderer supporting all platforms.
• The Skija renderer is experimental and mainly exists to have a desktop renderer that has Direct3D and Metal as its underlying graphics API, instead of relying on OpenGL.

Older versions of MultimediaLib used to support additional renderers, such as JavaFX, PixiJS, and three.js. However, with the current selection of renderers, these alternative implementations are no longer necessary.

When using a browser-based renderer, the application needs to be transpiled to JavaScript using via TeaVM in order for it to run. MultimediaLib comes with a command line tool that can be used to transpile the application as part of the build. The browser-based version can also be embedded inside a mobile app and run as a PWA.

Both Java applications and browser applications can be wrapped to native distributions for various platforms. Refer to the documentation on distributing applications for instructions on how to provide a more native distribution for each platform.

Architecture

MultimediaLib uses an architecture that is reminiscent of the old Macromedia Flash. Applications are structured in a similar way, and MultimediaLib also uses theater-inspired terminology for these concepts.

Each application consists of the following concepts:

• The renderer, which provided access to the underlying platform (graphics, audio, input, files, network). Different renderers are provided for different platforms, as explained in the section on supported platforms. MultimediaLib application code is renderer-independent, allowing the same application to run across different platforms.
• Scenes are the top-level structure to divide an application into different "chapters". Only one scene can be active at the same time. Simple applications may consist of a single scene, but larger applications can be split into multiple scenes, with each scene representing a different chapter or phase.
• The scene context is provided to the currently active scene by the renderer, allowing the scene to access the stage, the scene's actors, and the underlying renderer.
• Actors are used to structure scene logic, with each actor being responsible for a certain functional scope. Only one scene can be active at the same time, but a scene can consist of many actors. Since actors have a smaller functional scope, they (unlike their parent scene) will not automatically receive access to the full scene context. The actor will receive frame updates for as long as its parent scene remains active.
• The stage contains the graphics and audio for the currently active scene. The stage can contain both 2D and 3D graphics in a scene graph, where transforming a parent node propagates to its children. While the scene has full control over the stage, this control cannot outlive the scene itself: at the end of the scene, the contents of the stage are cleared so the next scene can take over.

Starting the demo application

MultimediaLib includes simple demo applications that showcase some of its features, and can be used as an example when using the framework to create applications. The demo applications can also be used for verification purposes when testing the framework on new platforms. Two demo applications are included: one for 2D graphics and one for 3D graphics.

To run the demo for desktop platforms, create a normal build of the library using gradle assemble, which builds both the desktop and browser versions.

To start the desktop version of the demo application, run the class nl.colorize.multimedialib.tool.DemoLauncher. This class supports the following command line parameters:

Name	Required	Description
--renderer	yes	One of 'java2d', 'javafx', 'gdx', 'skija'.
--graphics	yes	Either '2d' or '3d'.
--framerate	no	Demo framerate, default is 60 fps.
--canvas	no	Uses a fixed canvas size to display graphics.

Transpiling applications to HTML/JavaScript

Applications using MultimediaLib are written in Java. However, these applications can be transpiled to a combination of HTML and JavaScript so that they can be distributed via the web. This is done using TeaVM. Transpilation is started using the TeaVMTranspilerTool that is included as part of the library, and supports the following arguments:

Name	Required	Description
--project	yes	Project name for the application.
--main	yes	Main class that acts as application entry point.
--resources	yes	Directory containing the application's resource files.
--out	yes	Output directory for the generated files.
--buildid	no	Build ID used for caching resource files, default is random.
--meta	no	Inserts <meta> tags into the HTML, passed as name:value.
--lang	no	Primary application language, defaults to en-US.
--demo	no	Overrides the application with the demo application, for testing purposes.

Loading image contents in JavaScript is not allowed unless when running on a remote host. This is not a problem for "true" web applications, but can be problematic if the JavaScript version of the application is embedded in a mobile app. For this reason, all image are converted to data URLs during transpilation, so that they can be used without these restrictions.

Packing images into a sprite atlas

A "sprite atlas" is a large image that consists of a large image that contains multiple sprites, with each sprite is identified by a name the coordinates of the sprite within the larger image. Loading images individually is a perfectly valid approach for smaller applications, but large applications dependent on numerous images tend to benefit from using a sprite atlas in terms of loading time.

MultimediaLib includes a command line tool that can be used to create a sprite atlas from a directory of images. This is done using the SpriteAtlasPacker that is included as part of the library, and supports the following arguments:

Name	Required	Description
--input	yes	Input directory containing images to process.
--output	yes	Output directory for saving the generated texture atlas.
--name	no	File name for generated sprite atlas, defaults to directory name.
--nested	no	Creates a separate sprite atlas for each subdirectory.
--flatten	no	Base region name on file name only, instead of relative path.

This will create a sprite using with the libGDX .atlas file format. This format is supported by all renderers; the fact that the file format originates from libGDX does not mean it is only supported by that renderer.

If a .anim file with the same name exists in the same directory as the .atlas file, animation data for the sprite atlas will be loaded from that file. These .anim files use a similar indentation-based format as the atlas itself:

walk
  walk1: 1
  walk2: 0.5

All image references in the .anim file refer to the corresponding images defined in the .atlas file. Each image will be displayed for the specified duration, in seconds. In addition to the animation frames, each animation can also define the special property loop (either true or false).

Distributing applications

MultimediaLib does not include a distribution mechanism for applications, but it integrates with other tools for each supported platform. Other tools can be used to create a native distribution:

• The Colorize Gradle application plugin is capable of building native applications and installers for various platforms.
• Launch4j can generate .exe files for Windows. Alternatively, the browser version can be submitted to the Windows Store as a PWA.
• PWA Builder can generate native apps for Windows, Android, and iOS based on a PWA.
• Cordova can wrap the web application in a hybrid web/native app for Android, iOS, and Mac.

More documentation

• JavaDoc

Build instructions

Building the library requires the following:

• Java JDK 25+
• Gradle

The following Gradle build tasks are available:

• gradle clean cleans the build directory
• gradle assemble creates the JAR file for distribution
• gradle test runs all unit tests
• gradle coverage runs all unit tests and reports on test coverage
• gradle javadoc generates the JavaDoc API documentation
• gradle dependencyUpdates checks for and reports on library updates
• gradle publishToMavenCentral publishes the library to Maven Central. Requires credentials.

Portability

In order to retain portability across all supported platforms, MultimediaLib is limited to a subset of the Java standard library. ArchitectureTest, which runs as part of the unit tests and uses ArchUnit, is used to validate these portability constraints.

Take extra care when introducing libraries that serialize and/or deserialize file formats. Those libraries tend to heavily rely on reflection, which has limited support on some of the platforms targeted by MultimediaLib. Usually, it is still possible to use libraries for those file formats, as long as you use non-reflection libraries (or the non-reflection parts of a library).

Note that applications created using MultimediaLib will have the same portability restrictions, so you may want to consider introducing similar tests for your application code.

License

Copyright 2009-2026 Colorize

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.