> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rktscripts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RKT Musicfy

> Sistema imersivo de música espacial e mesa de DJ para FiveM.

# Introdução

O **RKT Musicfy** é um sistema de som imersivo para FiveM. Ele combina um player de música estilo Spotify, uma caixa de som Bluetooth portátil, rádio de veículo com acústica realista, e uma mesa de DJ completa com dois decks e crossfader — tudo construído sobre áudio espacial 3D de verdade.

<CardGroup cols={2}>
  <Card title="Áudio Espacial 3D" icon="volume-high">
    Volume com queda por distância, alcance por classe de veículo e abafamento dinâmico por portas/teto.
  </Card>

  <Card title="Handoff Bluetooth" icon="bluetooth">
    Mova sua sessão de música entre a caixa de som portátil e o rádio de qualquer veículo, sem interrupção.
  </Card>

  <Card title="Mesa de DJ" icon="record-vinyl">
    Dois decks independentes com crossfader, modo monitor, controle de pitch e seek.
  </Card>

  <Card title="Playlists e Busca" icon="magnifying-glass">
    Busque no YouTube direto no jogo, salve playlists no banco de dados e compartilhe as públicas.
  </Card>
</CardGroup>

## Início Rápido

1. **Download**: coloque a pasta `rkt_musicfy` no diretório `resources` do seu servidor.
2. **Dependências**: requer `ox_lib` e `oxmysql`. O recurso `xsound` só é necessário se você definir `Config.AudioEngine = "xsound"` — por padrão o Musicfy usa seu próprio motor de áudio nativo.
3. **Instale o motor de busca**: rode `npm install` dentro da pasta `rkt_musicfy`. Isso instala o `youtube-search-api`, usado por `server/search.js` para a busca dentro do jogo.
4. **Inicie o recurso**: adicione `ensure rkt_musicfy` na configuração do servidor, depois de `ox_lib` e `oxmysql`.

<Info>
  Se o `npm install` não foi executado, a busca por nome vai falhar — links diretos do YouTube continuam funcionando, pois não dependem do motor de busca em JS.
</Info>

## Configuração

Todas as configurações ficam em `config.lua`.

```lua theme={null}
Config.Debug = true

-- Engine de áudio: "xsound" (dependência externa) ou "native" (embutida no próprio script)
Config.AudioEngine = "native"

Config.MaxDistance = 20.0      -- Distância padrão para o rádio (caixa de som)
Config.DefaultVolume = 0.5

-- Distância de alcance por classe de veículo
Config.VehicleDistances = {
    ["default"] = 20.0,
    ["super"]   = 25.0,
    ["utility"] = 40.0,        -- Ex: carros de som/vans
}

Config.BoomboxProp = `prop_boombox_01`

-- Mesa de DJ
Config.DJBooth = {
    coords   = vector3(0.0, 0.0, 0.0),
    distance = 25.0,
}

-- Comandos
Config.Commands = {
    open = "spotify",
    dj   = "dj",
}
```

| Campo                         | Descrição                                                                                                    |
| :---------------------------- | :----------------------------------------------------------------------------------------------------------- |
| `AudioEngine`                 | `"native"` usa o motor embutido (sem dependência extra). `"xsound"` delega a reprodução ao recurso `xsound`. |
| `MaxDistance`                 | Alcance padrão, em metros, da caixa de som portátil.                                                         |
| `VehicleDistances`            | Alcance por classe de veículo — usa `default` quando a classe não está listada.                              |
| `BoomboxProp`                 | Modelo do prop gerado quando a música toca fora de um veículo.                                               |
| `DJBooth.coords` / `distance` | Posição e raio de transmissão da mesa de DJ. Ajuste `coords` para a posição real no seu mapa.                |
| `Commands.open` / `dj`        | Nome dos comandos de chat para o player e para a mesa de DJ.                                                 |

## Comandos e Atalhos

| Comando                       | Descrição                                      |
| :---------------------------- | :--------------------------------------------- |
| `/spotify`                    | Abre a interface do player de música.          |
| `/dj`                         | Abre a interface da Mesa de DJ.                |
| `/musica_vol [0-100]`         | Define seu volume master pessoal.              |
| `G` (atalho `musicfy_toggle`) | Solta a caixa de som no chão ou pega de volta. |

## Como Funciona

A sessão de música de cada jogador fica vinculada a uma única entidade "dona do som" — sua caixa de som portátil ou o veículo em que está.

<Steps>
  <Step title="Play">
    Dar play sem nenhuma entidade ativa gera uma caixa de som (a pé) ou toca direto pelo rádio do veículo em que você está.
  </Step>

  <Step title="Conectar Bluetooth">
    Entrar em um veículo com a caixa de som ativa transfere a sessão para o rádio do veículo, e vice-versa ao sair.
  </Step>

  <Step title="Acústica">
    O som do veículo fica abafado (volume e alcance reduzidos) sempre que todas as portas, janelas e o teto estão fechados — e volta ao normal instantaneamente ao abrir qualquer um.
  </Step>

  <Step title="Parada Automática">
    Se a entidade dona do som for deletada ou sumir, a sessão para automaticamente para todos que estavam ouvindo.
  </Step>
</Steps>

As sessões são sincronizadas pelo servidor, então quem entra durante uma sessão em andamento — ou está perto da entidade quando o recurso reinicia — ouve a música já em progresso.

## Mesa de DJ

A Mesa de DJ é um sistema independente de dois decks (`A` e `B`) que transmite a partir de uma posição fixa (`Config.DJBooth`), separado da sessão pessoal de caixa de som/rádio de qualquer jogador.

* **Crossfader e volume por deck** — misture entre os decks ao vivo.
* **Modo monitor** — o DJ pode ouvir um deck em particular, no volume máximo, sem afetar o mix público.
* **Controle de pitch** — taxa de reprodução ajustável entre `0.5x` e `2.0x`.
* **Seek e progresso sincronizado** — avance/retroceda as faixas com atualização de posição a cada 250ms.

## Playlists e Busca

A busca aceita nome de música/artista (resolvido pelo motor de busca do YouTube embutido) ou um link direto do YouTube/áudio. Os resultados podem ser tocados imediatamente, salvos nos favoritos, ou adicionados a uma playlist.

As playlists são armazenadas na tabela `musicfy_playlists`:

| Coluna                 | Descrição                                                                  |
| :--------------------- | :------------------------------------------------------------------------- |
| `owner`                | Identificador do jogador (Steam, ou license como alternativa).             |
| `name` / `description` | Metadados da playlist.                                                     |
| `songs`                | Array JSON com as faixas.                                                  |
| `is_public`            | Quando ativado, a playlist fica visível e importável por qualquer jogador. |

<Info>
  Playlists públicas podem ser importadas (clonadas) por outros jogadores para sua própria biblioteca através da interface do jogo.
</Info>