Spinatra

A dual-controller music player application with real-time audio visualization and song information display. This project combines hardware controls (rotary encoder, dual controllers), a Python backend, and a modern TypeScript/React frontend.

Project Structure

Core Files

• spinatra_dual_controller.py: Main Python application that manages audio playback, controller input, and communication with the frontend
• spinatra_controller.ino: Arduino sketch for the primary hardware controller
• requirements.txt: Python dependencies

Frontend (frontend/)

A TypeScript/React application built with Vite:

• App.tsx: Main React component
• main.tsx: Application entry point
• style.css: Global styles
• index.html: HTML template
• tsconfig.json: TypeScript configuration
• vite.config.ts: Vite build configuration
• components/: Reusable React components
  • AudioVisualizer.tsx: Real-time audio visualization component
• hooks/: Custom React hooks
  • useFrequencyData.ts: Hook for managing frequency data from audio analysis
• public/: Static assets

Backend Components

Audio Processing (Audio processing/)

Documentation and tools for audio processing:

• audioprocessing.md: Audio processing implementation details

Song Information (Song Information/)

Tools for fetching and managing song metadata:

• fetch_song_data.py: Script to query the Google Gemini API for song metadata
• song_data.txt: JSON file containing metadata and fun facts for all songs
• README.md: Documentation for song metadata tools

Songs (Songs/)

A collection of song lyric files organized by artist/song:

• American Idiot
• As It Was
• Bound 2
• Brianstorm
• Fly Me To The Moon
• Karma Police
• Sugar on my Tongue
• Summer
• The Less I Know the Better
• Timeless

Hardware (rotary_encoder/)

• rotary_encoder.ino: Arduino sketch for rotary encoder control integration

Getting Started

Prerequisites

• Python 3.x
• Node.js and npm (for frontend development)
• Arduino IDE (for hardware programming)

Installation

1. Install Python dependencies:

   pip install -r requirements.txt

2. Install frontend dependencies:

   cd frontend
   npm install

Running the Application

Backend:

python spinatra_dual_controller.py

Frontend (Development):

cd frontend
npm run dev

Frontend (Build):

cd frontend
npm run build

Features

• Dual Controller Support: Hardware support for multiple input controllers
• Real-time Audio Visualization: Live frequency analysis and visual representation
• Song Information: Fetches and displays interesting facts about songs using AI
• Hardware Integration: Arduino-based controller input via rotary encoder and dual controllers

API Integration

The Song Information module uses the Google Gemini API to fetch metadata about songs. Configure your API key via the GEMINI_API_KEY environment variable.

Development

The project uses:

• Frontend: React + TypeScript + Vite
• Backend: Python with audio processing and hardware control
• Hardware: Arduino (ESP32 or compatible boards)

License

MIT License