> For the complete documentation index, see [llms.txt](https://unknown-56-works.gitbook.io/luigiscreen/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unknown-56-works.gitbook.io/luigiscreen/control-studio/media-library.md).

# Media Library

Media Library indexes local files inside:

```
plugins/LuigiScreen/media/
```

Supported local extensions:

| Type      | Extensions                              |
| --------- | --------------------------------------- |
| Video     | `.mp4`, `.mkv`, `.webm`, `.mov`, `.avi` |
| Image     | `.png`, `.jpg`, `.jpeg`, `.webp`        |
| Animation | `.gif`                                  |

## Automatic watcher

The media folder and its existing subfolders are watched outside the Minecraft main thread. Adding, changing or removing a file triggers a debounced rescan.

You no longer need `/screen reload` after adding normal local media.

Use **Rescan Media** if a network-mounted filesystem does not emit file watcher events.

## Validation

Every entry reports:

* source type
* file size
* image/GIF dimensions when available immediately
* modification time
* number of playlist/event references
* validation result
* aggregate play count and planned playback time

Images that cannot be decoded, empty files and unsupported extensions are marked invalid. Video decoding is verified when the thumbnail or playback worker opens the file.

## Thumbnails

Thumbnail creation runs on the dedicated Media Library executor:

* images and GIFs use their decoded image
* videos use the first usable FFmpeg video frame
* the image is fitted into a centered 128x128 map canvas
* generated PNG files are cached in `.thumbnails/`

A Minecraft map ID is allocated only when that media entry is actually shown in the GUI. The ID is saved in `studio.yml` and reused after restart.

This avoids allocating a map for every file during startup.

## Cueing

In Web Studio, media cards have two visible production buttons:

| Button              | Result                                                              |
| ------------------- | ------------------------------------------------------------------- |
| **Add to playlist** | Adds the media to the playlist selected at the top of Media Library |
| **Play now**        | Temporarily plays the media on the selected live target             |

If no playlist exists yet, open **Playlist Editor** and create one first.

For in-game Control Studio, first select a screen from the Screens page.

| Click | Result                           |
| ----- | -------------------------------- |
| Left  | Play the media immediately       |
| Right | Add it after the current content |

Both actions are runtime overrides. They do not rewrite the screen's configured fallback source.

## References and deletion

References show how many `config.yml` values point to the relative media path. The first alpha does not delete files from the GUI.

Safe deletion procedure:

1. Check the References count.
2. Remove or replace references in affected playlists/events.
3. Publish the draft.
4. Delete the file from `plugins/LuigiScreen/media/`.
5. Confirm that Media Library removes it automatically.

This conservative behavior prevents one accidental inventory click from deleting a server file.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://unknown-56-works.gitbook.io/luigiscreen/control-studio/media-library.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.