How capdevon/simplemediaplayer works
1. What this repo is
- SimpleMediaPlayer is a Java library/plugin for jMonkeyEngine (jME) that plays media, with a strong focus on MJPEG video and screen-space visual effects.
- The README indicates it is an optimized fork of another SimpleMediaPlayer project, and it requires jME plus JDK 11+.
2. Primary architectural boundary
- The project is split between:
- a media playback layer (jme.media.player)
- a video generation/test utility layer (wpm.mjpeg)
- runtime assets in src/main/resources for shaders, sample media, and models.
- The main integration point is the jME scene graph and material system, not a standalone UI or server.
3. Core player API
- SimpleMediaPlayer is the likely high-level façade used by applications.
- MediaConfig holds playback/configuration parameters.
- MediaPlayerFactory centralizes player construction so callers do not instantiate codec/rendering pieces directly.
4. Playback and decoding pipeline
- VideoCodec defines the abstraction for decoding/producing video frames.
- VideoMjpegCodec is the concrete implementation for MJPEG streams/files.
- This suggests a pipeline of:
- media source/configuration
- codec decoding
- frame delivery to the rendering side.
5. Rendering integration with jME
- VideoScreenAdapter and VideoScreenListener are the bridge between decoded video frames and the rendering target.
- They isolate the media pipeline from the actual scene graph/material update mechanism, which is important for keeping jME-specific code at the edge of the system.
6. Scene lifecycle integration
- MediaAppState integrates the player into the jME application lifecycle.
- In jME terms, this means media playback is managed as an application state rather than ad hoc from game logic, so setup/update/disposal are tied to the engine lifecycle.
7. Effect subsystem
- MediaEffectManager manages post-processing or shader-driven effects on the media output.
- The README shows supported toggles such as:
- LCD
- VHS
- scanline
- glitch
- black-and-white
- It also calls out several effects that “don’t work” in the original version, which signals that effects are implemented as a distinct layer on top of the base video rendering, likely via material/shader parameters.
8. Shader/material assets
- src/main/resources/MatDefs/SimpleMediaPlayer contains:
- SimpleMediaPlayer.j3md
- SimpleMediaPlayer.vert
- SimpleMediaPlayer.frag
- This is the material/shader boundary that turns video frames into a textured, effectable surface in jME.
9. Media and sample assets
- src/main/resources/Media includes multiple .mjpg files at different resolutions plus audio.ogg.
- This indicates the repo includes sample playback assets and likely uses them for demos/tests or benchmarking different video sizes.
- Textures/Media and Models/testScene.* support scene-based examples rather than a pure headless library.
10. MJPEG generation tooling
- wpm.mjpeg.MJPEGGenerator is a utility for producing MJPEG content.
- The presence of Test_MJPEGEncoder and Test_MJPEGGenerator suggests this area is used to validate the encoding/generation path independently from the jME player.
11. Tests and demo scenes
- jme.media.player.test contains IntroStateTest, MenuGeometryTest, and ScreenMaterialTest.
- These are likely executable jME demos or integration tests that exercise:
- application state bootstrapping
- scene/menu geometry interaction
- media screen material/shader behavior
12. Build and delivery
- The project uses Gradle with the wrapper checked in, making it self-contained to build.
- .github/workflows/push.yml indicates CI automation on pushes, so the repo is set up for repeatable builds/tests.
13. How the pieces fit together
- An application creates a player through MediaPlayerFactory, configures it with MediaConfig, and attaches it through MediaAppState.
- VideoMjpegCodec decodes MJPEG media and forwards frames through the screen adapter/listener path.
- The frame ends up in a jME material defined by the SimpleMediaPlayer shader assets, where MediaEffectManager can enable visual effects.
14. Key diagram boundaries to show
- Application / jME scene graph
- Media player core API
- Codec/decoder layer
- Video frame-to-material adapter
- Shader/material effects
- Sample assets and MJPEG generator utilities
Main entry points: SimpleMediaPlayer.j3md Shader Def · VideoScreenAdapter.java Screen Adapter · MediaPlayerFactory.java Player Factory · MediaAppState.java Media AppState
Components 21
jME integration
Application-state and scene-graph entry points for using the library inside jMonkeyEngine.
- Media AppState · Integrates media playback into the jME application lifecycle.
src/main/java/jme/media/player/MediaAppState.java
Player core
High-level API, configuration, lifecycle, and effect management.
- SimpleMediaPlayer · Top-level entry point for applications embedding media playback.
src/main/java/jme/media/player/SimpleMediaPlayer.java - MediaConfig · Playback and source configuration for the media pipeline.
src/main/java/jme/media/player/MediaConfig.java - Player Factory · Central construction point for player instances and related wiring.
src/main/java/jme/media/player/MediaPlayerFactory.java - Effect Manager · Controls post-processing and shader-driven media effects.
src/main/java/jme/media/player/MediaEffectManager.java
Video pipeline
Codec and frame-delivery components for MJPEG playback.
- VideoCodec · Abstraction for decoding or producing video frames.
src/main/java/jme/media/player/VideoCodec.java - MJPEG Codec · Concrete MJPEG decoding implementation used by the player.
src/main/java/jme/media/player/VideoMjpegCodec.java - Screen Adapter · Connects decoded frames to the render target and material updates.
src/main/java/jme/media/player/VideoScreenAdapter.java - Screen Listener · Listener interface for frame delivery and screen update events.
src/main/java/jme/media/player/VideoScreenListener.java
Runtime assets
Shader/material definitions and bundled media/model assets used at runtime.
- Shader Def · jME material definition for rendering media with effects.
src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.j3md - Vertex Shader · Vertex-stage shader for the media material.
src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.vert - Fragment Shader · Fragment-stage shader for the media material and effects.
src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.frag - Sample Media · Bundled MJPEG clips and audio used for demos and validation.
src/main/resources/Media - Test Models · Bundled scene assets for material and scene integration examples.
src/main/resources/Models/testScene.j3o - Media Textures · Texture assets used by the media screen and sample scenes.
src/main/resources/Textures/Media
MJPEG tools
Utility code for generating and validating MJPEG content.
- MJPEG Generator · Utility for generating MJPEG content.
src/main/java/wpm/mjpeg/MJPEGGenerator.java - Encoder Test · Validation utility for the MJPEG encoding path.
src/main/java/wpm/mjpeg/Test_MJPEGEncoder.java - Generator Test · Validation utility for the MJPEG generation path.
src/main/java/wpm/mjpeg/Test_MJPEGGenerator.java
Demo tests
Executable demos and integration checks for the player and material setup.
- Intro Test · jME demo for application-state bootstrapping.
src/main/java/jme/media/player/test/IntroStateTest.java - Menu Test · jME demo for scene/menu geometry interaction.
src/main/java/jme/media/player/test/MenuGeometryTest.java - Screen Test · jME demo for media screen and shader behavior.
src/main/java/jme/media/player/test/ScreenMaterialTest.java
Connections 21
- SimpleMediaPlayer → Player Factory: creates · Facade delegates construction to the factory.
- SimpleMediaPlayer → MediaConfig: uses · Playback is driven by configuration parameters.
- Player Factory → VideoCodec: wires · Factory assembles codec-backed playback components.
- Player Factory → Screen Adapter: wires · Factory connects decoding output to rendering.
- Media AppState → SimpleMediaPlayer: hosts · Application state manages the player during the jME lifecycle.
- Media AppState → Effect Manager: controls · State-level integration can enable and manage effects.
- VideoCodec → MJPEG Codec: implemented by · MJPEG codec is the concrete decoding path.
- MJPEG Codec → Screen Adapter: delivers frames · Decoded frames are forwarded toward the screen bridge.
- Screen Adapter → Screen Listener: notifies · Adapter emits frame and update events to listeners.
- Screen Adapter → Shader Def: updates · Rendered frames land in the media material.
- Shader Def → Vertex Shader: includes · Material definition references the vertex shader.
- Shader Def → Fragment Shader: includes · Material definition references the fragment shader.
- Effect Manager → Shader Def: configures · Effects are applied through shader/material parameters.
- Fragment Shader → Effect Manager: implements effects · Fragment shader is where visual effect toggles take effect.
- Sample Media → MJPEG Codec: feeds · Bundled MJPEG clips exercise the playback path.
- Test Models → Menu Test: supports · Scene model backs the menu/geometry demo.
- Media Textures → Screen Test: supports · Texture assets support screen-material validation.
- MJPEG Generator → Encoder Test: validated by · Encoder test exercises generation output.
- MJPEG Generator → Generator Test: validated by · Generator test exercises MJPEG creation.
- Intro Test → Media AppState: exercises · Demo boots the media application state.
- Screen Test → Shader Def: exercises · Demo validates the material/shader path.