🎵 Widget Música

Widget de controle de mídia para o KDE Plasma 6 — mostra a capa do álbum, título/artista, barra de progresso e controles de reprodução da música que está tocando, integrando com qualquer player compatível com MPRIS2.

Funciona com Spotify, VLC, navegadores (Firefox/Chromium tocando vídeo ou música), Elisa, e wrappers como o Sidra (Apple Music) — qualquer aplicativo que exponha a interface MPRIS2 via D-Bus.

---

✨ Funcionalidades

• Capa do álbum com fallback para ícone quando não há arte disponível
• Título e artista da faixa atual
• Barra de progresso com tempo decorrido / restante (e busca arrastando, se o player suportar)
• Controles: anterior, play/pause, próxima
• Shuffle (aleatório) e Repeat (repetir faixa / playlist)
• Volume com slider
• Seletor de player quando há mais de um tocando ao mesmo tempo
• Transparência do fundo configurável (desktop)
• Duas representações automáticas:
  • No painel: versão compacta (capa pequena + nome + anterior/play-pause/próxima)
  • Expandida / desktop: tudo acima, com a capa grande

---

📦 Requisitos

• KDE Plasma 6 (testado no Fedora KDE com libplasma 6.7)
• Pacotes de desenvolvimento:

Fedora:

sudo dnf install plasma-sdk libplasma-devel qt6-qtdeclarative-devel

openSUSE:

sudo zypper install plasma6-sdk libplasma6-devel qt6-declarative-devel

Arch / Manjaro:

sudo pacman -S plasma-sdk

plasma-sdk traz o plasmoidviewer, usado para testar o widget sem reiniciar o Plasma inteiro.

---

🚀 Instalação

Opção mais fácil — direto pelo Plasma (KDE Store)

Sem precisar clonar nada:

1. Clique direito no painel ou na área de trabalho → Adicionar Widgets...
2. Botão Obter Novos Widgets → Baixar Novos Widgets do Plasma
3. Busque por "Widget Musica" e clique em Instalar

Ou baixe direto da página na KDE Store: https://www.opendesktop.org/p/2363408/

As opções abaixo são para quem quer instalar a partir do código-fonte ou desenvolver.

Opção A — Script (recomendado)

git clone https://github.com/dnsouzadev/widget-musica.git
cd widget-musica
./install.sh

Depois recarregue o Plasma:

kquitapp6 plasmashell && kstart plasmashell

O install.sh cria um symlink da pasta package/ para ~/.local/share/plasma/plasmoids/ — assim qualquer alteração no código já reflete no widget. Outras opções:

./install.sh --copy        # copia os arquivos em vez de symlink
./install.sh --uninstall   # remove o widget

Opção B — Manual

mkdir -p ~/.local/share/plasma/plasmoids
ln -sfn "$(pwd)/package" ~/.local/share/plasma/plasmoids/com.dnsouzadev.widgetmusica
kquitapp6 plasmashell && kstart plasmashell

Adicionar no painel ou desktop

• Painel: clique direito no painel → Adicionar Widgets... → procure por "Widget Musica"
• Desktop: clique direito na área de trabalho → Adicionar Widgets... → mesma busca

---

⚙️ Configuração

Clique direito no widget → Configurar Widget Musica... → aba Aparência:

• Transparência do fundo (0–100%): controla a opacidade do fundo desenhado pelo próprio widget. Padrão 60.

⚠️ Limitação conhecida: a transparência funciona no desktop, mas não no popup do painel. O popup é uma janela separada controlada pelo Plasma (PlasmaQuick::Dialog) e não é possível forçar transparência real nela via QML — nem widgets de referência maduros (como o plasmusic-toolbar) conseguem.

---

🧪 Desenvolvimento

Testar sem reiniciar o Plasma

# representação expandida (como ficaria no desktop)
plasmoidviewer -a com.dnsouzadev.widgetmusica

# representação compacta (como ficaria num painel horizontal no topo)
plasmoidviewer -a com.dnsouzadev.widgetmusica -f horizontal -l topedge

Erros de QML aparecem no terminal. Ignore os avisos de isScreenUiReady e qt.svg.draw — são ruído do containment padrão do viewer, não têm relação com este widget.

Estrutura do projeto

widget-musica/
├── README.md
├── LICENSE
├── install.sh                        ← instalador (symlink / copy / uninstall)
└── package/                          ← o plasmoid em si
    ├── metadata.json                 ← id, nome, versão, licença, autor
    └── contents/
        ├── ui/
        │   ├── main.qml              ← estado compartilhado (MPRIS) + escolhe a representação
        │   ├── Compact.qml           ← representação compacta (painel)
        │   ├── Full.qml              ← representação expandida (popup / desktop)
        │   └── config/
        │       └── General.qml       ← UI da página "Configurar Widget"
        └── config/
            ├── main.xml              ← schema das configurações (KConfigXT)
            └── config.qml            ← registra a aba "Aparência"

Como funciona (visão técnica)

• A integração com os players usa o módulo QML privado do Plasma org.kde.plasma.private.mpris (o mesmo do controle de mídia oficial do KDE). Ele expõe um Mpris2Model com a lista de players ativos e um currentPlayer com propriedades (track, artist, artUrl, position, length, volume, shuffle, loopStatus) e métodos (Next(), Previous(), PlayPause()).
• main.qml cria o Mpris2Model e expõe player, ready e isPlaying como propriedades do PlasmoidItem (id root). Compact.qml e Full.qml acessam esse estado via root.player etc. — funciona porque o Plasma carrega as representações no mesmo contexto QML do main.qml.
• A posição (position) não é atualizada automaticamente pelo D-Bus, então um Timer em Full.qml chama player.updatePosition() a cada 500ms enquanto toca e o slider não está sendo arrastado.
• Shuffle/repeat só funcionam se o player expuser essas propriedades opcionais do MPRIS. Players que não suportam deixam os botões desabilitados — é limitação do player, não do widget (ex.: alguns wrappers não implementam).
• A capa não aparece na representação compacta quando o painel é muito fino: o RowLayout não recorta conteúdo que excede a altura disponível, e calcular o tamanho da capa a partir da altura real do painel se mostrou frágil. Por isso ela é exibida com tamanho proporcional à espessura do painel.

Erros comuns (e a causa)

Erro	Causa
module "org.kde.plasmoid" is not installed	import errado — o correto é org.kde.plasma.plasmoid
main.qml must be of type PlasmoidItem	no Plasma 6 a raiz do main.qml precisa ser PlasmoidItem
root item ... does not implement QQuickItem	erro de sintaxe no QML (ex.: vírgulas entre property bindings, que não existem em QML)
KPackageStructure ... does not match	falta "KPackageStructure": "Plasma/Applet" no metadata.json
Conteúdo "vazando" pra fora do painel	Layout.preferredWidth/Height é tratado como mínimo dentro de um RowLayout — se o painel for mais fino, o item transborda em vez de encolher; dimensione a partir da espessura real e/ou use clip

---

🤝 Como colaborar

Contribuições são bem-vindas! O fluxo padrão no GitHub:

1. Faça um fork do repositório (botão Fork no topo da página em github.com/dnsouzadev/widget-musica).
2. Clone o seu fork e crie uma branch para a sua mudança:

   git clone https://github.com/SEU_USUARIO/widget-musica.git
   cd widget-musica
   git checkout -b minha-melhoria

3. Instale em modo desenvolvimento para testar enquanto edita:

   ./install.sh

4. Faça suas alterações nos arquivos .qml dentro de package/contents/ui/. Teste com o plasmoidviewer (não precisa reiniciar o Plasma a cada edição):

   plasmoidviewer -a com.dnsouzadev.widgetmusica

5. Commit e push na sua branch:

   git add .
   git commit -m "Adiciona X"
   git push origin minha-melhoria

6. Abra um Pull Request do seu fork para o repositório original, descrevendo o que mudou e (se for visual) anexando um print.

Dicas para PRs

• Mantenha o estilo do código existente (indentação de 4 espaços, nomes descritivos).
• Mudanças visuais: inclua um screenshot do antes/depois.
• Encontrou um bug mas não vai corrigir? Abra uma issue descrevendo o passo a passo para reproduzir, sua versão do Plasma (plasmashell --version) e o player usado.

Ideias de melhorias futuras

• Estado vazio mais elaborado quando nenhum player está ativo
• Tooltip no painel com mais detalhes da faixa
• Cor de fundo personalizada (além da transparência)
• Atalho de teclado global para play/pause

---

📄 Licença

Distribuído sob a licença MIT. Veja o arquivo LICENSE para o texto completo.

Você pode usar, copiar, modificar e redistribuir livremente, mantendo o aviso de copyright.

---

👤 Autor

Daniel Souza GitHub: @dnsouzadev

Se este widget te foi útil, deixa uma ⭐ no repositório!