Uma API RESTful para estudo de download de músicas e playlists do Spotify, utilizando FastAPI e processamento paralelo para gerenciar downloads simultâneos.
Este projeto foi desenvolvido com o objetivo de:
- Aprender e demonstrar conceitos de desenvolvimento de APIs com Python
- Explorar o uso de bibliotecas e ferramentas modernas do ecossistema Python
- Estudar padrões de arquitetura de software e boas práticas
- Experimentar com processamento paralelo e gerenciamento de filas
- Compreender sistemas de autenticação e autorização
⚖️ Responsabilidade Legal: O usuário é responsável por garantir que qualquer uso deste código esteja em conformidade com as leis locais e termos de serviço das plataformas utilizadas.
- FastAPI - Framework web moderno e rápido para Python
- Uvicorn - Servidor ASGI para aplicações Python
- Pydantic - Validação de dados e configurações
- SQLAlchemy - ORM para Python
- PyMySQL - Driver MySQL para Python
- python-jose - Implementação JWT para Python
- passlib - Biblioteca para hash de senhas
- bcrypt - Função de hash criptográfica
- Spotipy - Biblioteca cliente para API do Spotify
- requests - Biblioteca HTTP para Python
- yt-dlp - Ferramenta para download de vídeos/áudios
- FFmpeg - Processamento e conversão de áudio (requisito externo)
- python-dotenv - Carregamento de variáveis de ambiente
- python-multipart - Suporte para dados multipart/form-data
- MySQL - Sistema de gerenciamento de banco de dados
- 🎵 Sistema de estudo para download de faixas e playlists
- 👥 Sistema de usuários com autenticação JWT
- 🔄 Gerenciamento de fila de downloads com processamento paralelo
- 📊 Acompanhamento de progresso em tempo real
- 🧩 Extração automática de ID de URL do Spotify
- 🔍 Busca integrada no Spotify
- 🛡️ Sistema de permissões para usuários e administradores
- Python 3.9+
- MySQL
- FFmpeg (para processamento de áudio)
- Credenciais de API do Spotify (client_id e client_secret)
-
Clone o repositório:
git clone https://github.com/gaab0418/SpotDown.git cd spotify-downloader-api -
Crie um ambiente virtual e ative-o:
python -m venv venv source venv/bin/activate # Linux/macOS # ou venv\Scripts\activate # Windows
-
Instale as dependências:
pip install -r requirements.txt
-
Configure o arquivo
.envna raiz do projeto:# Configuração do MySQL MYSQL_HOST=<host> # Exemplo: localhost MYSQL_PORT=<porta> # Exemplo: 3306 MYSQL_USER=<usuario> # Exemplo: root MYSQL_PASSWORD=<senha> # Exemplo: root MYSQL_DATABASE=<banco_de_dados> # Exemplo: musicDb # Configuração JWT JWT_SECRET_KEY=<chave> # Exemplo: He4l0W0rld # Configuração do Spotify SPOTIFY_CLIENT_ID=<client_id> # Exemplo: 123456789abcd0123456789abcd SPOTIFY_CLIENT_SECRET=<client_secret> # Exemplo: 123456789abcd0123456789abcd SPOTIFY_REDIRECT_URI=<redirect_uri> # Exemplo: http://127.0.0.1:8888/callback # Configuração da API API_HOST=<host> # Exemplo: 0.0.0.0 API_PORT=<porta> # Exemplo: 8801 # Configuração de downloads DOWNLOAD_PATH=<caminho> # Exemplo: ./arqvs/download MAX_CONCURRENT_DOWNLOADS=<limite> # Exemplo: 10 -
Crie o banco de dados MySQL:
CREATE DATABASE musicDb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-
Execute a aplicação:
python main.py
-
Acesse a documentação Swagger da API em:
http://localhost:8801/docs -
Crie um usuário:
curl -X POST "http://localhost:8801/users/" \ -H "Content-Type: application/json" \ -d '{"username": "seunome", "email": "seu@email.com", "password": "suasenha"}'
-
Obtenha um token de acesso:
curl -X POST "http://localhost:8801/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "username=seunome&password=suasenha"
-
Configure suas credenciais do Spotify:
curl -X POST "http://localhost:8801/spotify/config" \ -H "Authorization: Bearer seu_token" \ -H "Content-Type: application/json" \ -d '{ "client_id": "seu_client_id_spotify", "client_secret": "seu_client_secret_spotify", "redirect_uri": "http://127.0.0.1:8888/callback", "download_path": "./downloads" }'
-
Inicie um download de teste:
curl -X POST "http://localhost:8801/downloads" \ -H "Authorization: Bearer seu_token" \ -H "Content-Type: application/json" \ -d '{ "spotify_id": "id_da_musica_ou_playlist", "type": "track", "priority": 5 }'
spotify-downloader-api/
├── auth.py # Autenticação e controle de acesso
├── config.py # Configurações da aplicação
├── database.py # Conexão com o banco de dados
├── download_queue.py # Gerenciamento da fila de downloads
├── downloader.py # Funções de download do Spotify
├── main.py # Aplicação FastAPI principal
├── models.py # Modelos SQLAlchemy e esquemas Pydantic
├── requirements.txt # Dependências do projeto
├── .env # Variáveis de ambiente (não versionado)
├── .env.example # Exemplo de configuração
├── README.md # Documentação do projeto
├── LICENSE.md # Licença
├── CONTRIBUTING.md # Contribuições educacionais
├── SECURITY.md # Informações de Segurança
└── CODE_OF_CONDUCT.md.md # Guia de contribuição
- O usuário autentica-se e recebe um token JWT
- O usuário configura suas credenciais do Spotify
- O usuário solicita um download de faixa ou playlist
- O download é adicionado à fila com uma prioridade
- O gerenciador de downloads processa os downloads em paralelo
- O usuário pode acompanhar o progresso do download
- Ao finalizar, o arquivo fica disponível para download
POST /users/- Criar novo usuárioPOST /token- Obter token de acessoGET /users/me- Dados do usuário atual
POST /spotify/config- Configurar credenciais do SpotifyGET /spotify/config- Obter configuração atualGET /search- Pesquisar no SpotifyPOST /extract-id- Extrair ID do Spotify de uma URL
POST /downloads- Iniciar novo downloadGET /downloads- Listar downloads do usuárioGET /downloads/{download_id}- Status de um download específicoDELETE /downloads/{download_id}- Cancelar um downloadGET /queue/status- Status da fila de downloadsGET /files/{file_path}- Baixar arquivo
GET /admin/users- Listar todos os usuáriosPUT /admin/users/{user_id}- Atualizar usuárioDELETE /admin/users/{user_id}- Excluir usuário
Este projeto demonstra diversos conceitos importantes:
- Arquitetura de APIs REST com FastAPI
- Autenticação JWT e controle de acesso
- ORM com SQLAlchemy para interação com banco de dados
- Processamento assíncrono e gerenciamento de filas
- Integração com APIs externas (Spotify API)
- Validação de dados com Pydantic
- Middleware e CORS para aplicações web
- Estruturação de projetos Python profissionais
- Documentação automática com OpenAPI/Swagger
- Este projeto é apenas para fins educacionais e de aprendizado
- Não incentivamos ou apoiamos o uso para download de conteúdo protegido por direitos autorais
- Os usuários são responsáveis por cumprir todas as leis aplicáveis e termos de serviço
- Este projeto não tem afiliação oficial com o Spotify
- Criar um frontend
Contribuições educacionais são bem-vindas! Por favor, leia o arquivo CODE_OF_CONDUCT.md para mais informações sobre como contribuir de forma educativa para este projeto.
Este projeto está licenciado sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.
Lembre-se: Este é um projeto educacional. Use-o para aprender sobre desenvolvimento Python, APIs e arquitetura de software. Sempre respeite os direitos autorais e termos de serviço das plataformas utilizadas.