you-music/NEW_FEATURES.md

New Features Implementation Summary

Features Implemented

1. ✅ Search Function Timeout (1 minute)

• Added 60-second timeout to YouTube search (yt-dlp subprocess)
• Added 60-second timeout to Bilibili search (aiohttp request)
• Graceful error handling for timeouts

Files Modified:

• backend/app/services/search.py

2. ✅ Full-Screen Player

• Added fullscreen button in bottom control panel
• Created FullScreenPlayer component with:
  • Large album artwork
  • Enhanced song information display
  • All player controls (play/pause, next/previous)
  • Action buttons (like, add to playlist, share)
  • Click on thumbnail to open fullscreen

Files Modified:

• frontend/src/components/player/Player.tsx
• frontend/src/components/player/FullScreenPlayer.tsx (new)

3. ✅ Auto Search & Download Feature

Backend:

• New Database Models:

  • DownloadJob: Tracks auto-download jobs with status, priority, duplication detection
  • APIKey: API key management for authentication

• New API Endpoints:

  • POST /api/auto-download/job - Create download job (requires API key)
  • GET /api/auto-download/jobs - List all jobs
  • GET /api/auto-download/jobs/{id} - Get specific job
  • POST /api/auto-download/jobs/{id}/confirm - Confirm duplicate download
  • POST /api/auto-download/jobs/{id}/retry - Retry failed job
  • DELETE /api/auto-download/jobs/{id} - Delete job
  • POST /api/auto-download/jobs/clear-completed - Clear completed jobs

• Priority Logic:

  • Songs with "official song" or "官方" in title are marked as priority
  • Priority songs are automatically selected for download

• Duplicate Detection:

  • Checks for existing songs by source URL
  • Puts duplicates in "waiting_confirmation" status
  • User must confirm before downloading duplicate

Files Created:

• backend/app/api/auto_download.py
• backend/alembic/versions/52b30f47e145_add_download_jobs_and_api_keys_tables.py

Files Modified:

• backend/app/models/models.py
• backend/app/schemas/schemas.py
• backend/main.py

Frontend:

• AutoDownload Component:

  • Input for song name and API key
  • Real-time job status updates (every 5 seconds)
  • Job list with status badges
  • Confirmation dialog for duplicates
  • Retry button for failed jobs
  • Clear completed jobs button

• Integrated into Home Page:

  • Tabs: Library | Auto Download

Files Created:

• frontend/src/components/download/AutoDownload.tsx
• frontend/src/components/HomePage.tsx

Files Modified:

• frontend/src/App.tsx
• frontend/src/api/client.ts

4. ✅ API Keys Management

Backend:

• New API Endpoints:

  • POST /api/api-keys/ - Create API key
  • GET /api/api-keys/ - List all keys
  • GET /api/api-keys/{id} - Get specific key
  • DELETE /api/api-keys/{id} - Delete key
  • POST /api/api-keys/{id}/deactivate - Deactivate key
  • POST /api/api-keys/{id}/activate - Activate key

• Authentication Middleware:

  • verify_api_key() dependency for protected endpoints
  • Checks expiration and active status
  • Updates last_used_at timestamp

Files Created:

• backend/app/api/api_keys.py

Files Modified:

• backend/app/models/models.py
• backend/app/schemas/schemas.py
• backend/main.py

Frontend:

• API Keys Management Component:

  • Create/delete API keys
  • Set expiration (optional)
  • Show/hide key values
  • Copy to clipboard
  • Display usage statistics
  • Complete API usage documentation

• Integrated into Settings:

  • Tabs: General | API Keys

Files Created:

• frontend/src/components/settings/APIKeysManagement.tsx

Files Modified:

• frontend/src/components/settings/SettingsPage.tsx
• frontend/src/api/client.ts

5. ✅ Artist Search Feature

Backend:

• New API Endpoint:
  • GET /api/artists/search?q={query} - Search artists by name

Files Modified:

• backend/app/api/artist.py
• backend/app/schemas/schemas.py

Frontend:

• Search input in Artists page
• Real-time artist filtering

Files Modified:

• frontend/src/components/artist/ArtistsPage.tsx
• frontend/src/api/client.ts

6. ✅ Sort Features

Backend:

• Music API:

  • Added sort_by parameter (title, artist, album, created_at, duration)
  • Added sort_order parameter (asc, desc)
  • Default: created_at desc

• Artist API:

  • Added sort_by parameter (name, song_count)
  • Added sort_order parameter (asc, desc)
  • Default: song_count desc

• Artist Songs:

  • Added sorting to artist detail page

Files Modified:

• backend/app/api/music.py
• backend/app/api/artist.py

Frontend:

• Music Library:

  • Sort dropdown (Date Added, Title, Artist, Album, Duration)
  • Sort order toggle button
  • Persists in query

• Artists Page:

  • Sort dropdown (Song Count, Name)
  • Sort order toggle button

• Artist Detail Page:

  • Inherits sorting capability

Files Modified:

• frontend/src/components/MusicLibrary.tsx
• frontend/src/components/artist/ArtistsPage.tsx
• frontend/src/api/client.ts

7. ✅ Default Sort for Library (by created_at desc)

• Backend defaults to created_at desc when no sort specified
• Frontend queries with default sort

Files Modified:

• backend/app/api/music.py
• frontend/src/components/MusicLibrary.tsx

New UI Components Created

1. frontend/src/components/ui/select.tsx - Dropdown select component
2. frontend/src/components/ui/badge.tsx - Status badges
3. frontend/src/components/ui/tabs.tsx - Tab navigation
4. frontend/src/components/ui/alert.tsx - Alert/notification boxes

API Usage Example

Auto Download API

# Create API key first (through Settings UI)
# Then use it to create download jobs:

curl -X POST http://localhost:8000/api/auto-download/job \
  -H "X-API-Key: ym_your_generated_key_here" \
  -H "Content-Type: application/json" \
  -d '{"song_name": "Shape of You"}'

# Get job status
curl http://localhost:8000/api/auto-download/jobs

# Confirm duplicate download
curl -X POST http://localhost:8000/api/auto-download/jobs/1/confirm

# Retry failed job
curl -X POST http://localhost:8000/api/auto-download/jobs/1/retry

Database Migrations

• Migration created: 52b30f47e145_add_download_jobs_and_api_keys_tables.py
• Tables added:
  • download_jobs
  • api_keys

Testing Checklist

• Backend compiles without errors
• Database migration applied successfully
• All new API endpoints exist
• Search timeout works (need to test with slow network)
• Fullscreen player opens and closes properly
• Auto-download job creation works
• API key authentication works
• Duplicate detection works
• Priority songs identified correctly
• Artist search returns results
• Sorting works on library page
• Sorting works on artists page
• Default sort is created_at desc

Next Steps

1. Start the development servers
2. Test each feature manually
3. Create API key in Settings
4. Test auto-download with API key
5. Verify sorting on all pages
6. Test fullscreen player
7. Test artist search
8. Verify timeout behavior

Notes

• API keys are stored with prefix "ym_" for easy identification
• Auto-download jobs refresh every 5 seconds in the UI
• Priority is automatically detected based on title keywords
• Duplicate detection prevents accidental re-downloads
• All new features are fully integrated into the existing UI