> For the complete documentation index, see [llms.txt](https://docs.fivemstats.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fivemstats.net/tgiann-fivem-stats-script/for-developers/screenshots-and-uploads.md).

# Screenshots and Uploads

Take screenshots of a player's screen and upload files from your own scripts.

Screenshots go from the player's game straight to the media service, never through FXServer. They need `screencapture` or `screenshot-basic` started before this script. Every file shows on the [Media](https://docs.fivemstats.net/panel/media.md) page. All exports are listed on [Exports](https://docs.fivemstats.net/tgiann-fivem-stats-script/for-developers/exports.md).

## A player's screen, from the server

```lua
local result, reason = exports["tgiann-fivem-stats-script"]:TakeServerImage(targetId, { reason = "report" })
if result then
    print(result.url)
else
    print("screenshot failed: " .. reason)
end
```

The player whose screen it is becomes the file's player. It waits up to **Screenshot timeout** ([Settings > Players and items](https://docs.fivemstats.net/panel/settings.md#players-and-items), 15 seconds by default).

## From the client

```lua
local result, reason = exports["tgiann-fivem-stats-script"]:TakeImage({ reason = "bug report" })
```

A player may start **Player screenshots** per minute ([Settings > Players and items](https://docs.fivemstats.net/panel/settings.md#players-and-items), 6 by default, `0` turns client screenshots off). The client cannot set the folder, the player or keep forever.

## Upload a file from the server

```lua
local file = exports["tgiann-fivem-stats-script"]:UploadBase64(base64, {
    filename = "house_12.webp",
    path = "housing/photos",
    metadata = { playerSource = source },
    retentionExempt = true,
})
print(file.url) -- https://media.yourserver.com/f/housing/photos/house_12.webp
```

JavaScript scripts can send a Buffer with `UploadImage(buffer, { fileName, path, metadata })`.

## Upload a JSON file

Data your script saves (a recording, a report, a replay) goes up the same way, plain or gzip compressed. It is stored byte for byte, up to 50 MB ([File formats](https://docs.fivemstats.net/tgiann-fivem-stats-script/media-service.md#file-formats)).

```lua
local file = exports["tgiann-fivem-stats-script"]:UploadBase64(gzipBase64, {
    filename = "recording_12.gz",
    path = "bodycam",
})
print(file.url) -- https://media.yourserver.com/f/bodycam/recording_12.gz
```

* Send it as raw base64 or as a `data:application/json` / `data:application/gzip` URI. A `data:image/...`, `data:video/...` or `data:audio/...` URI is never stored as JSON, so a file a player sent as a photo cannot become a data file.
* The file must be one complete JSON value, nested at most 256 levels deep. A gzip file is checked after unpacking and may unpack to at most 512 MB. Anything else is refused.
* A gzip file is served as `application/gzip` and stays compressed, so the script that downloads it unpacks it (in a NUI: `DecompressionStream("gzip")`).

## File names and fixed addresses

| You upload                                       | The address is                         | Uploading again                                                            |
| ------------------------------------------------ | -------------------------------------- | -------------------------------------------------------------------------- |
| With a `filename`                                | `<public address>/f/<path>/<filename>` | The same folder and name **replaces** the file; the address stays the same |
| Without a `filename` (screenshots, upload links) | `<public address>/f/<path>/<id>.webp`  | Always a new file                                                          |

* With a name you can build the address yourself and open it from anywhere, like Fivemanage.
* The extension follows the stored format: images are converted to WebP, so `house_12.png` becomes `house_12.webp`; a JSON file ends in `.json`, a gzip one in `.gz`. Letters, digits, `_`, `-` and `.` are kept, upper case too; other characters become `-`.
* A replaced file is checked again by browsers, so the new picture shows without adding `?v=` to the address.
* Moving a named file to another folder in the panel changes its address to the new folder. Its id address (`/f/<id>.webp`) never changes.
* `GetFile` and `DeleteFile` accept the id, the address or `<path>/<filename>`.

## A single-use upload link

```lua
local url = exports["tgiann-fivem-stats-script"]:RequestPresignedUrl("image", { path = "phone/photos", expiresIn = 120 })
```

Give the link to a NUI or a client. It accepts one file of that type (`image`, `video`, `audio` or `json`), sent as a multipart form field named `file`. A link made without a type accepts images, videos and audio, never JSON. The uploader cannot change the folder, the metadata or keep forever, and the file always gets its own id: a player can never replace a file by its name.

Every upload answers:

```json
{ "status": "ok", "data": { "id": "k3v9...", "url": "https://203.0.113.10:6174/f/...", "originalUrl": "..." } }
```

## Folders, players and keep forever

| Option                   | What it does in the panel                                                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path`                   | The folder on the [Media](https://docs.fivemstats.net/panel/media.md) page, for example `mdt/evidence`                                            |
| `metadata.playerSource`  | The player the file belongs to. Their identifiers and character are added, so the Media page shows the name and can filter by player              |
| `metadata.targetSource`  | A second player the file is about (the reported player, the victim)                                                                               |
| `retentionExempt = true` | **Keep forever**: never removed by the media retention in [Settings > Media storage](https://docs.fivemstats.net/panel/settings.md#media-storage) |

Metadata keys starting with `_` are reserved for the server and are dropped when they come from a client.

## Scripts written for fmsdk

The resource provides `fmsdk` and uses the same export names, so scripts written for fmsdk work without changes. Remove the fmsdk resource itself.

## Test it

Run `/mediatest` in game as an admin, see [Admin Commands](https://docs.fivemstats.net/tgiann-fivem-stats-script/admin-commands.md).
