🛠️ Troubleshooting

Common Issues

Detailed Troubleshooting

1. Hotkey Not Working

Symptoms:

• Pressing Ctrl + / does nothing
• No recording indicator appears

Solutions:

macOS Permissions

1. Open System Preferences → Security & Privacy → Privacy
2. Select Accessibility
3. Add your Terminal app (Terminal.app, iTerm2, etc.)
4. Check the box next to your terminal
5. Restart the terminal and WinterMelon Scribe

Test Keyboard Simulation

# In Python
import pyautogui
pyautogui.typewrite('test')

2. Paste Not Working

Symptoms:

• Transcription works but nothing is pasted
• Text appears in terminal but not in target app

Solutions:

Screen Recording Permission

1. Open System Preferences → Security & Privacy → Privacy
2. Select Screen Recording
3. Add your Terminal app
4. Restart after granting permission

Focus Issues

• Click in the target application first
• Ensure cursor is visible
• Try pressing Ctrl + / quickly

3. Empty Transcription

Symptoms:

• Recording works but returns empty text
• No errors but no output

Solutions:

Check Microphone

1. System Preferences → Sound → Input
2. Select correct microphone
3. Test with other apps (Voice Memos)

Verify API Configuration

# Check .env file
cat .env | grep API_KEY

Test API Connection

# For SiliconFlow
curl -X POST https://api.siliconflow.cn/v1/audio/transcriptions \
  -H "Authorization: Bearer $SILICONFLOW_API_KEY"

4. Service Management

Check Service Status

./status.sh

Manual Service Control

# Stop service
launchctl stop com.wintermelon.scribe
 
# Start service
launchctl start com.wintermelon.scribe

View Logs

# Runtime logs
tail -f logs/wintermelon_scribe.log
 
# Error logs
tail -f logs/wintermelon_scribe.err
 
# View last 50 lines
tail -50 logs/wintermelon_scribe.log

5. Provider-Specific Issues

SiliconFlow

• Error: "Invalid API Key"

  • Verify key is correct, no extra spaces
  • Check account status

• Error: "Model not found"

  • Use default: FunAudioLLM/SenseVoiceSmall
  • Check model availability

Groq

• Error: "Rate limit exceeded"

  • Wait between requests
  • Check usage limits

• Error: "Invalid model"

  • Use whisper-large-v3-turbo
  • Check Groq documentation

OpenAI (LLM)

• Error: "Insufficient credits"
  • Check account balance
  • Add credits or switch to smaller model

FAQ

Q: How do I completely reset WinterMelon Scribe?

# Uninstall completely
./uninstall.sh
 
# Remove configuration
rm -rf .env logs/
 
# Reinstall from scratch
./install.sh

Q: Can I run multiple instances?

Not recommended. Use one instance per user for best performance.

Q: How to update API keys?

1. Edit .env file
2. Run: ./uninstall.sh && ./install.sh
3. Or restart if in developer mode

Q: Why does transcription fail on first try?

• macOS may need extra time to grant permissions
• Try restarting after permission changes
• Check system console for error messages

Getting Help

Collect Debug Information

# Create debug report
./status.sh > debug_report.txt
 
# Include logs
cat logs/wintermelonscribe.log >> debug_report.txt
 
# Share the report when asking for help

Report Issues

When reporting issues, include:

1. macOS version
2. Python version
3. Error messages
4. Steps to reproduce
5. Debug report (if possible)

Community Support

• GitHub Issues: Report bugs and request features
• Documentation: Check for latest updates

Performance Tips

Improve Accuracy

• Use quality microphone
• Reduce background noise
• Speak clearly and at moderate pace
• Use same language throughout session

Reduce Latency

• Check internet connection
• Try different provider (Groq for speed)
• Close unnecessary applications

Save Bandwidth

• Use shorter recording sessions
• Disable LLM if not needed
• Monitor usage regularly