# capdevon/simplemediaplayer architecture

> Architecture diagram of the GitHub repository capdevon/simplemediaplayer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/capdevon/simplemediaplayer
- Repository: https://github.com/capdevon/simplemediaplayer

## Overview

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: [`src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.j3md`](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.j3md) (Shader Def), [`src/main/java/jme/media/player/VideoScreenAdapter.java`](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/VideoScreenAdapter.java) (Screen Adapter), [`src/main/java/jme/media/player/MediaPlayerFactory.java`](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/MediaPlayerFactory.java) (Player Factory), [`src/main/java/jme/media/player/MediaAppState.java`](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/MediaAppState.java) (Media AppState)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["jME integration"]
  node_node_app_state["Media AppState<br/>jME state<br/>[MediaAppState.java]"]
end

subgraph group_group_core["Player core"]
  node_node_simple_player["SimpleMediaPlayer<br/>façade"]
  node_node_media_config["MediaConfig<br/>[MediaConfig.java]"]
  node_node_player_factory(("Player Factory"))
  node_node_effect_manager["Effect Manager<br/>effects"]
end

subgraph group_group_codec["Video pipeline"]
  node_node_video_codec["VideoCodec<br/>codec interface<br/>[VideoCodec.java]"]
  node_node_mjpeg_codec["MJPEG Codec<br/>decoder"]
  node_node_screen_adapter["Screen Adapter<br/>bridge"]
  node_node_screen_listener["Screen Listener<br/>callback"]
end

subgraph group_group_assets["Runtime assets"]
  node_node_shader_def["Shader Def<br/>material definition"]
  node_node_shader_vert["Vertex Shader"]
  node_node_shader_frag["Fragment Shader"]
  node_node_media_assets[("Sample Media<br/>assets")]
  node_node_models_assets["Test Models<br/>assets<br/>[testScene.j3o]"]
  node_node_textures_assets[("Media Textures<br/>assets")]
end

subgraph group_group_tools["MJPEG tools"]
  node_node_mjpeg_gen["MJPEG Generator"]
  node_node_encoder_test["Encoder Test<br/>utility test"]
  node_node_generator_test["Generator Test<br/>utility test"]
end

subgraph group_group_demos["Demo tests"]
  node_node_intro_test["Intro Test<br/>demo state"]
  node_node_menu_test["Menu Test<br/>demo scene"]
  node_node_screen_test["Screen Test<br/>demo material"]
end

node_node_simple_player -->|"creates"| node_node_player_factory
node_node_simple_player -->|"uses"| node_node_media_config
node_node_player_factory -->|"wires"| node_node_video_codec
node_node_player_factory -->|"wires"| node_node_screen_adapter
node_node_app_state -->|"hosts"| node_node_simple_player
node_node_app_state -->|"controls"| node_node_effect_manager
node_node_video_codec -->|"implemented by"| node_node_mjpeg_codec
node_node_mjpeg_codec -->|"delivers frames"| node_node_screen_adapter
node_node_screen_adapter -->|"notifies"| node_node_screen_listener
node_node_screen_adapter -->|"updates"| node_node_shader_def
node_node_shader_def -->|"includes"| node_node_shader_vert
node_node_shader_def -->|"includes"| node_node_shader_frag
node_node_effect_manager -->|"configures"| node_node_shader_def
node_node_shader_frag -->|"implements effects"| node_node_effect_manager
node_node_media_assets -->|"feeds"| node_node_mjpeg_codec
node_node_models_assets -->|"supports"| node_node_menu_test
node_node_textures_assets -->|"supports"| node_node_screen_test
node_node_mjpeg_gen -->|"validated by"| node_node_encoder_test
node_node_mjpeg_gen -->|"validated by"| node_node_generator_test
node_node_intro_test -->|"exercises"| node_node_app_state
node_node_screen_test -->|"exercises"| node_node_shader_def

click node_node_simple_player "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/SimpleMediaPlayer.java"
click node_node_media_config "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/MediaConfig.java"
click node_node_player_factory "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/MediaPlayerFactory.java"
click node_node_app_state "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/MediaAppState.java"
click node_node_effect_manager "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/MediaEffectManager.java"
click node_node_video_codec "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/VideoCodec.java"
click node_node_mjpeg_codec "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/VideoMjpegCodec.java"
click node_node_screen_adapter "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/VideoScreenAdapter.java"
click node_node_screen_listener "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/VideoScreenListener.java"
click node_node_shader_def "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.j3md"
click node_node_shader_vert "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.vert"
click node_node_shader_frag "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.frag"
click node_node_media_assets "https://github.com/capdevon/simplemediaplayer/tree/main/src/main/resources/Media"
click node_node_models_assets "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/resources/Models/testScene.j3o"
click node_node_textures_assets "https://github.com/capdevon/simplemediaplayer/tree/main/src/main/resources/Textures/Media"
click node_node_mjpeg_gen "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/wpm/mjpeg/MJPEGGenerator.java"
click node_node_encoder_test "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/wpm/mjpeg/Test_MJPEGEncoder.java"
click node_node_generator_test "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/wpm/mjpeg/Test_MJPEGGenerator.java"
click node_node_intro_test "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/test/IntroStateTest.java"
click node_node_menu_test "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/test/MenuGeometryTest.java"
click node_node_screen_test "https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/test/ScreenMaterialTest.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_app_state toneBlue
class node_node_simple_player,node_node_media_config,node_node_player_factory,node_node_effect_manager toneAmber
class node_node_video_codec,node_node_mjpeg_codec,node_node_screen_adapter,node_node_screen_listener toneMint
class node_node_shader_def,node_node_shader_vert,node_node_shader_frag,node_node_media_assets,node_node_models_assets,node_node_textures_assets toneRose
class node_node_mjpeg_gen,node_node_encoder_test,node_node_generator_test toneIndigo
class node_node_intro_test,node_node_menu_test,node_node_screen_test toneTeal
```

## Components

### jME integration

Application-state and scene-graph entry points for using the library inside jMonkeyEngine.

- [Media AppState](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/MediaAppState.java): jME state · 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](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/SimpleMediaPlayer.java): façade · Top-level entry point for applications embedding media playback. · `src/main/java/jme/media/player/SimpleMediaPlayer.java`
- [MediaConfig](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/MediaConfig.java): config · Playback and source configuration for the media pipeline. · `src/main/java/jme/media/player/MediaConfig.java`
- [Player Factory](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/MediaPlayerFactory.java): factory · Central construction point for player instances and related wiring. · `src/main/java/jme/media/player/MediaPlayerFactory.java`
- [Effect Manager](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/MediaEffectManager.java): effects · 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](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/VideoCodec.java): codec interface · Abstraction for decoding or producing video frames. · `src/main/java/jme/media/player/VideoCodec.java`
- [MJPEG Codec](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/VideoMjpegCodec.java): decoder · Concrete MJPEG decoding implementation used by the player. · `src/main/java/jme/media/player/VideoMjpegCodec.java`
- [Screen Adapter](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/VideoScreenAdapter.java): bridge · Connects decoded frames to the render target and material updates. · `src/main/java/jme/media/player/VideoScreenAdapter.java`
- [Screen Listener](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/VideoScreenListener.java): callback · 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](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.j3md): material definition · jME material definition for rendering media with effects. · `src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.j3md`
- [Vertex Shader](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.vert): shader · Vertex-stage shader for the media material. · `src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.vert`
- [Fragment Shader](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.frag): shader · Fragment-stage shader for the media material and effects. · `src/main/resources/MatDefs/SimpleMediaPlayer/SimpleMediaPlayer.frag`
- [Sample Media](https://github.com/capdevon/simplemediaplayer/tree/main/src/main/resources/Media): assets · Bundled MJPEG clips and audio used for demos and validation. · `src/main/resources/Media`
- [Test Models](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/resources/Models/testScene.j3o): assets · Bundled scene assets for material and scene integration examples. · `src/main/resources/Models/testScene.j3o`
- [Media Textures](https://github.com/capdevon/simplemediaplayer/tree/main/src/main/resources/Textures/Media): assets · 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](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/wpm/mjpeg/MJPEGGenerator.java): utility · Utility for generating MJPEG content. · `src/main/java/wpm/mjpeg/MJPEGGenerator.java`
- [Encoder Test](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/wpm/mjpeg/Test_MJPEGEncoder.java): utility test · Validation utility for the MJPEG encoding path. · `src/main/java/wpm/mjpeg/Test_MJPEGEncoder.java`
- [Generator Test](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/wpm/mjpeg/Test_MJPEGGenerator.java): utility 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](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/test/IntroStateTest.java): demo state · jME demo for application-state bootstrapping. · `src/main/java/jme/media/player/test/IntroStateTest.java`
- [Menu Test](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/test/MenuGeometryTest.java): demo scene · jME demo for scene/menu geometry interaction. · `src/main/java/jme/media/player/test/MenuGeometryTest.java`
- [Screen Test](https://github.com/capdevon/simplemediaplayer/blob/main/src/main/java/jme/media/player/test/ScreenMaterialTest.java): demo material · jME demo for media screen and shader behavior. · `src/main/java/jme/media/player/test/ScreenMaterialTest.java`

## Connections

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