Troubleshooting

Troubleshooting

한국어

Solutions to common issues with ivLyrics.

---

Reset ivLyrics

If you experience issues with settings or lyrics display, try resetting the app:

1. Run spicetify enable-devtools in your terminal
2. Right-click in the Spotify window and select "Inspect Element" or "Developer Tools"
3. Go to Application tab > Storage > Click Clear site data
4. Press Ctrl+Shift+R (macOS: Cmd+Shift+R) to reload Spotify

---

Common Issues

Lyrics Not Displaying

Symptoms: No lyrics appear for any song

Solutions:

1. Check your internet connection
2. Verify lyrics providers are enabled in Settings
3. Try a different song (some songs may not have lyrics available)
4. Clear the lyrics cache in Settings > Advanced
5. Check if the song is playing (lyrics only show for playing tracks)

---

Translation Not Working

Symptoms: Translation button doesn't work or shows errors

Solutions:

1. Verify your API key is correctly entered in AI Provider settings
2. Check that the API key is valid and not expired
3. Ensure the AI provider is enabled and has translation capability enabled
4. Check your API quota (free tiers have usage limits)
5. Try a different AI provider

---

Wrong Translation Language

Symptoms: Translation appears in a different language than expected

Solutions:

1. Go to Settings > Translation
2. Verify the target language is correctly set
3. Clear translation cache and try again

---

Lyrics Out of Sync

Symptoms: Lyrics are ahead or behind the music

Solutions:

1. Hover over lyrics to show controls
2. Use the sync offset adjustment
3. Try community sync data if available
4. Adjust offset manually (+ for delayed lyrics, - for early lyrics)

---

Spotify Won't Start

Symptoms: Spotify crashes or doesn't open after installing ivLyrics

Solutions:

1. Open terminal and run:

   spicetify restore
   spicetify apply
   

2. If issue persists, try reinstalling:

   spicetify config custom_apps ivLyrics-
   spicetify apply
   

3. Then reinstall ivLyrics

---

Fullscreen Mode Issues

Symptoms: Fullscreen mode doesn't work or glitches

Solutions:

1. Try pressing the fullscreen shortcut again (F12 by default)
2. Click in the Spotify window first before pressing the shortcut
3. Check if another extension is conflicting
4. Disable and re-enable fullscreen in settings

---

API Errors

Symptoms: "API Error", "Rate Limited", or "Quota Exceeded" messages

Solutions:

Error	Solution
Invalid API Key	Re-enter your API key
Rate Limited	Wait a few minutes and try again
Quota Exceeded	Wait until quota resets or upgrade plan
Network Error	Check internet connection

---

High Memory Usage

Symptoms: Spotify becomes slow or uses too much memory

Solutions:

1. Clear all caches in Settings > Advanced
2. Disable video background if enabled
3. Reduce animation effects
4. Restart Spotify periodically

---

Black Screen in Fullscreen

Symptoms: Fullscreen shows black screen with no lyrics

Solutions:

1. Wait a few seconds for content to load
2. Press Esc to exit and try again
3. Clear browser cache (see Reset section above)
4. Disable video background temporarily

---

Keyboard Shortcuts Not Working

Symptoms: F12 or other shortcuts don't respond

Solutions:

1. Click inside the Spotify window first
2. Make sure no other application is using the same shortcut
3. Check shortcut settings in Settings > Keyboard Shortcuts
4. Try changing to a different shortcut key

---

Getting Help

If the above solutions don't resolve your issue:

1. Check Existing Issues: GitHub Issues
2. Join Discord: Community Discord
3. Create New Issue: Include:
   • ivLyrics version
   • Spotify version
   • Operating system
   • Steps to reproduce
   • Error messages (if any)

---

Debug Information

To collect debug information:

1. Enable debug mode in Settings > Advanced
2. Reproduce the issue
3. Open Developer Tools (Ctrl+Shift+I or right-click > Inspect)
4. Go to the Console tab
5. Copy any error messages

---

Related

• Getting Started - Installation guide
• Settings - Configuration options