Skip to content

GabrielFinotti/ytune-app

BranchesTags

Repository files navigation

🎵 YTune App

Aplicativo web moderno para download de músicas do YouTube

Next.js React TypeScript Tailwind CSS License Version Docker

Interface web responsiva e moderna para a YTune API

Demo • Documentação • API • Reportar Bug

YTune App Preview

📋 Sobre o Projeto

O YTune App é uma aplicação web desenvolvida com as mais recentes tecnologias do ecossistema React, oferecendo uma experiência moderna, rápida e intuitiva para download de músicas do YouTube em formato MP3 de alta qualidade.

✨ Principais Funcionalidades

  • 🎨 Design Moderno - Interface clean com efeitos interativos de blur seguindo o mouse
  • 📱 Mobile First - Totalmente responsivo para todos os dispositivos
  • 🌓 Tema Claro/Escuro - Alternância suave com persistência no localStorage
  • ✏️ Edição de Título - Personalize o nome do arquivo antes de baixar
  • ⚡ Performance Otimizada - Build com Turbopack e otimizações do Next.js 15
  • 🎵 Alta Qualidade - Download de áudio MP3 com qualidade preservada
  • 🔒 Privacidade Garantida - Processamento 100% privado, sem armazenamento de dados
  • 🎯 UX Premium - Cards 3D interativos, blur effects e animações suaves
  • 🐳 Docker Ready - Containerização completa com docker-compose
  • 🔍 SEO Otimizado - Meta tags, sitemap, robots.txt e favicons multiplataforma

🚀 Stack Tecnológica

Core

Bibliotecas e Ferramentas

Desenvolvimento

  • ESLint - Linting e formatação de código
  • PostCSS - Processamento CSS avançado
  • Docker - Containerização com multi-stage builds
  • Sharp - Geração de favicons otimizados

📦 Pré-requisitos

Antes de começar, certifique-se de ter instalado:

🔧 Instalação e Configuração

1️⃣ Clone o Repositório

git clone https://github.com/GabrielFinotti/ytune-app.git
cd ytune-app

2️⃣ Instale as Dependências

npm install
# ou
yarn install
# ou
pnpm install

3️⃣ Configure as Variáveis de Ambiente

Crie um arquivo .env.local na raiz do projeto:

# URL da YTune API (ajuste conforme seu ambiente)
NEXT_PUBLIC_API_URL=http://localhost:3000

💡 Dica: Para produção, atualize a URL para o endereço do seu servidor de API.

4️⃣ Inicie a YTune API

Certifique-se de que a YTune API está rodando:

# Em outro terminal, na pasta da API
cd ytune-api
npm run dev

⚠️ Importante: Configure o CORS na API para permitir requisições do frontend:

expose_headers=["X-Track-Title", "X-Track-Filename", "X-Track-Duration", "Content-Disposition"]

5️⃣ Inicie o Aplicativo

npm run dev

Abra http://localhost:3000 no navegador.

📝 Nota: Se a porta 3000 estiver em uso, o Next.js usará automaticamente a próxima porta disponível (3001, 3002, etc.).

🐳 Instalação com Docker

O YTune App está pronto para ser executado com Docker, facilitando o deploy em qualquer ambiente.

Pré-requisitos

  • Docker 20.10 ou superior
  • Docker Compose 2.0 ou superior

Método 1: Docker Compose (Recomendado)

# 1. Clone o repositório
git clone https://github.com/GabrielFinotti/ytune-app.git
cd ytune-app

# 2. Configure as variáveis de ambiente
cp .env.local.example .env.local
# Edite o .env.local com a URL da sua API

# 3. Inicie com docker-compose
npm run docker:up
# ou
docker compose up -d

A aplicação estará disponível em http://localhost:3000.

Método 2: Docker Build Manual

# Build da imagem
docker build -t ytune-app .

# Execute o container
docker run -p 3000:3000 --env-file .env.local ytune-app

Scripts Docker Disponíveis

# Build das imagens
npm run docker:build

# Iniciar containers em background
npm run docker:up

# Parar containers
npm run docker:down

# Ver logs em tempo real
npm run docker:logs

# Reiniciar containers
npm run docker:restart

# Rebuild completo (sem cache)
npm run docker:rebuild

# Build e deploy para produção
npm run docker:prod

Recursos do Docker

  • ✅ Multi-stage build - Imagem otimizada (~150MB)
  • ✅ Node Alpine - Base leve e segura
  • ✅ Cache otimizado - Layers separados para dependencies
  • ✅ Non-root user - Maior segurança
  • ✅ Health checks - Monitoramento automático
  • ✅ Auto-restart - Reinicialização em caso de falha

🚀 Deploy em Produção

Para deploy em produção com Docker, siga estas etapas:

1️⃣ Configure as Variáveis de Ambiente

Crie um arquivo .env no servidor com as variáveis de produção:

PORT=3000
NEXT_PUBLIC_BASE_URL=https://seu-dominio.com
NEXT_PUBLIC_API_URL=https://api.seu-dominio.com/api/v1

⚠️ Importante: As variáveis NEXT_PUBLIC_* são embutidas no código durante o build. Sempre faça rebuild completo ao alterá-las.

2️⃣ Build e Deploy

# Pare a aplicação atual
docker-compose down

# Remova a imagem antiga (força rebuild)
docker rmi ytune-app:latest

# Build com as novas variáveis
docker-compose build --no-cache

# Inicie a aplicação
docker-compose up -d

3️⃣ Verificação

# Verifique os logs
docker-compose logs -f app

# Teste a aplicação
curl https://seu-dominio.com

🎯 Scripts Disponíveis

# Desenvolvimento com Turbopack (hot reload)
npm run dev

# Build otimizado para produção
npm run build

# Iniciar servidor de produção (após build)
npm start

# Análise de código e correção automática
npm run lint

# Type checking
npx tsc --noEmit

🎨 Funcionalidades Detalhadas

🔍 Download de Músicas

  1. Cole a URL do vídeo do YouTube no campo de input
  2. Validação automática verifica se a URL é válida
  3. Clique em "Baixar Música" para processar
  4. Aguarde o processamento da API
  5. Modal de edição abre automaticamente com o título da música

✏️ Edição de Título

  • O modal é pré-carregado com o título original da música (via header X-Track-Title)
  • Edite o nome do arquivo como preferir
  • Visualize o nome final com extensão .mp3
  • Pressione Enter para confirmar ou Esc para cancelar
  • O download inicia automaticamente após confirmação

🌓 Sistema de Tema

  • Detecção automática da preferência do sistema
  • Alternância manual via botão (Sun/Moon icon)
  • Persistência no localStorage
  • Transições suaves entre temas (500ms)
  • Cores otimizadas para cada tema:
    • Light: Base cinza clara com acentos emerald
    • Dark: OLED black com gradientes emerald mais escuros

🎭 Efeitos Interativos

  • Blur Dinâmico: Efeito de blur que segue o movimento do mouse em:
    • Botão principal de download
    • Campo de input
    • Botões do modal (Cancelar e Baixar)
  • Cards 3D: Features cards com rotação 3D baseada na posição do mouse
  • Hover States: Transições suaves em todos os elementos interativos
  • Cursors Apropriados:
    • cursor-pointer em botões ativos
    • cursor-text em campos de texto
    • cursor-not-allowed quando desabilitado

📱 Responsividade

  • Mobile (< 768px): Layout em coluna única, cards empilhados
  • Tablet (768px - 1024px): Grid de 2 colunas para features
  • Desktop (> 1024px): Layout completo com 3 colunas

📂 Estrutura do Projeto

ytune-app/
├── public/                        # Arquivos estáticos
│   ├── favicon.svg               # Favicon principal (SVG)
│   ├── favicon-16x16.png         # Favicon 16x16
│   ├── favicon-32x32.png         # Favicon 32x32
│   ├── apple-touch-icon.png      # Ícone Apple (180x180)
│   ├── icon-192.png              # PWA icon 192x192
│   ├── icon-512.png              # PWA icon 512x512
│   └── manifest.json             # Web App Manifest
├── scripts/
│   └── generate-favicons.js      # Script de geração de favicons
├── src/
│   ├── app/
│   │   ├── globals.css           # Estilos globais e utilitários Tailwind
│   │   ├── layout.tsx            # Root layout com providers e metadata
│   │   ├── page.tsx              # Página principal (Home)
│   │   ├── robots.ts             # Configuração robots.txt dinâmico
│   │   └── sitemap.ts            # Geração de sitemap.xml
│   ├── components/
│   │   ├── EditTitleModal.tsx    # Modal de edição de título
│   │   ├── FeatureCard.tsx       # Card 3D interativo
│   │   ├── InteractiveButton.tsx # Botão com blur interativo
│   │   ├── InteractiveInput.tsx  # Input com blur interativo
│   │   ├── LoadingSpinner.tsx    # Spinner de carregamento
│   │   ├── Logo.tsx              # Logo animado
│   │   ├── Providers.tsx         # Providers wrapper
│   │   └── ThemeToggle.tsx       # Botão de alternância de tema
│   ├── contexts/
│   │   └── ThemeContext.tsx      # Context API para tema global
│   ├── services/
│   │   └── api.ts                # Serviço de comunicação com API
│   └── types/
│       └── index.ts              # Definições de tipos TypeScript
├── .dockerignore                  # Arquivos ignorados pelo Docker
├── .env.local                     # Variáveis de ambiente (não versionado)
├── .env.local.example            # Exemplo de variáveis de ambiente
├── .eslintrc.json                # Configuração ESLint
├── .gitignore                    # Arquivos ignorados pelo Git
├── CHANGELOG.md                  # Registro de mudanças por versão
├── docker-compose.yml            # Configuração Docker Compose
├── Dockerfile                    # Imagem Docker multi-stage
├── DOCKER.md                     # Documentação Docker
├── LICENSE                       # Licença MIT
├── next.config.ts                # Configuração Next.js
├── package.json                  # Dependências e scripts
├── postcss.config.mjs            # Configuração PostCSS
├── README.md                     # Este arquivo
├── tailwind.config.ts            # Configuração Tailwind CSS
└── tsconfig.json                 # Configuração TypeScript

🔌 Integração com a API

Endpoints Utilizados

// Download de áudio
GET /api/v1/download?url={youtube_url}

// Health check
GET /api/v1/health

Estrutura de Resposta

interface DownloadResponse {
  buffer: ArrayBuffer;      // Dados binários do arquivo MP3
  title: string;            // Título da música (sem extensão)
  duration: number;         // Duração em segundos
  size: number;             // Tamanho do arquivo em bytes
  filename: string;         // Nome do arquivo com extensão
}

Headers Customizados

A API deve retornar os seguintes headers (expostos via CORS):

  • X-Track-Title: Título original da música
  • X-Track-Filename: Nome do arquivo sanitizado
  • X-Track-Duration: Duração da música em segundos
  • Content-Disposition: Metadata do arquivo para download

Exemplo de Uso

import { downloadAudio } from '@/services/api';

const response = await downloadAudio('https://youtube.com/watch?v=...');
console.log(response.title);    // "Nome da Música"
console.log(response.duration); // 180 (3 minutos)
console.log(response.size);     // 5242880 (5 MB)

🎨 Design System

Paleta de Cores

Tema Claro

  • Background: #F9FAFB (gray-50)
  • Surface: #FFFFFF + #ECFDF580 (white + emerald-50/80)
  • Primary: #065F46, #047857, #059669 (emerald-700/600)
  • Text: #111827 (gray-900)

Tema Escuro

  • Background: #111827 (gray-950) - OLED optimized
  • Surface: #1F293780 (gray-900/60) com backdrop-blur
  • Primary: #065F46, #047857 (darker emerald)
  • Text: #F9FAFB (gray-50)

Gradientes

/* Gradiente primário (botões) */
.gradient-bg-primary {
  background: linear-gradient(135deg, #065f46, #047857, #059669);
}

/* Gradiente de texto */
.gradient-text {
  background: linear-gradient(135deg, #047857, #10b981, #14b8a6);
  -webkit-background-clip: text;
}

Transições

  • Padrão: 300ms ease-in-out
  • Hover States: transform, opacity, shadow
  • Tema Toggle: 500ms ease-in-out

📊 Versionamento

Este projeto segue o Semantic Versioning 2.0.0.

Versão Atual: 1.2.0 (2025-10-11)

Para ver o histórico completo de mudanças, consulte o CHANGELOG.md.

Formato de Versão

MAJOR.MINOR.PATCH

MAJOR: Mudanças incompatíveis na API
MINOR: Novas funcionalidades compatíveis
PATCH: Correções de bugs compatíveis

🚧 Roadmap

v1.3.0 (Próxima Release)

  • Sistema de histórico de downloads
  • Atalhos de teclado (Ctrl+V para colar URL)
  • Indicador de progresso detalhado
  • Suporte a múltiplos idiomas (i18n)

v1.4.0

  • Download de playlists completas
  • Preview de áudio antes do download
  • Sistema de favoritos com localStorage

v2.0.0

  • Múltiplos formatos (WAV, FLAC, AAC, OGG)
  • Conversão de bitrate customizada
  • Sistema de contas de usuário
  • Modo offline

Backlog

  • Testes automatizados (Jest + Testing Library)
  • CI/CD com GitHub Actions
  • Analytics e métricas
  • Sistema de compartilhamento

✅ Concluído

  • v1.2.0: Suporte a variáveis de ambiente no Docker para produção
  • v1.1.0: Docker containerization, SEO, PWA, favicons e migração para Fetch API
  • v1.0.0: Lançamento inicial com todas as funcionalidades principais

🤝 Contribuindo

Contribuições são sempre bem-vindas! Este projeto segue o Contributor Covenant Code of Conduct.

Como Contribuir

  1. Fork o projeto

  2. Crie uma branch para sua feature:

    git checkout -b feature/MinhaNovaFeature

  3. Commit suas mudanças seguindo o padrão:

    git commit -m 'feat: Adiciona nova funcionalidade X'

  4. Push para a branch:

    git push origin feature/MinhaNovaFeature

  5. Abra um Pull Request descrevendo suas mudanças

Padrão de Commits

Seguimos o Conventional Commits:

  • feat: Nova funcionalidade
  • fix: Correção de bug
  • docs: Atualização de documentação
  • style: Formatação, espaços, etc.
  • refactor: Refatoração de código
  • test: Adição ou correção de testes
  • chore: Tarefas de manutenção

🧪 Testes

# Executar testes unitários (a implementar)
npm run test

# Executar testes com coverage (a implementar)
npm run test:coverage

# Executar testes E2E (a implementar)
npm run test:e2e

📄 Licença

Este projeto está licenciado sob a Licença MIT. Veja o arquivo LICENSE para mais detalhes.

MIT License

Copyright (c) 2025 Gabriel H. Finotti

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

👤 Autor

Gabriel H. Finotti

GitHub LinkedIn

Projetos Relacionados

  • YTune API - Backend FastAPI para download de músicas

🙏 Agradecimentos

Agradecimentos especiais às seguintes tecnologias e comunidades:

📞 Suporte

Encontrou um Bug?

  1. Verifique se já existe uma Issue aberta
  2. Se não, crie uma nova Issue com:
    • Descrição clara do problema
    • Passos para reproduzir
    • Comportamento esperado vs atual
    • Screenshots (se aplicável)
    • Informações do ambiente (OS, browser, Node version)

Tem uma Sugestão?

Abra uma Feature Request descrevendo:

  • Qual problema a feature resolve
  • Como ela deveria funcionar
  • Exemplos de uso

📈 Status do Projeto

GitHub last commit GitHub issues GitHub pull requests

Feito com ❤️ por Gabriel Finotti

⭐ Se este projeto te ajudou, considere dar uma estrela! ⭐

⬆ Voltar ao topo

About

Aplicativo prático e simples para download de músicas do Youtube na melhor qualidade disponível

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.2.1 Latest
Oct 11, 2025

Packages

No packages published

Languages