rehearshalhub/DEBUGGING_GUIDE.md

Debugging Guide for Comment Waveform Integration

Current Status

The code changes have been implemented, but the functionality may not be working as expected. This guide will help identify and fix the issues.

Debugging Steps

1. Check Browser Console

Open the browser developer tools (F12) and check the Console tab:

What to look for:

• TypeScript errors (red text)
• API request failures
• JavaScript errors
• Debug logs from our console.log statements

Expected debug output:

Creating comment with timestamp: 45.678
Comment created successfully
Comments data: [ {...}, {...} ]
Processing comment: abc-123 timestamp: 45.678 avatar: https://example.com/avatar.jpg
Adding marker at time: 45.678

2. Check Network Requests

In browser developer tools, go to the Network tab:

Requests to check:

1. POST /api/v1/songs/{song_id}/comments - Comment creation

   • Check request payload includes timestamp
   • Check response status is 201 Created
   • Check response includes author_avatar_url

2. GET /api/v1/songs/{song_id}/comments - Comment listing

   • Check response includes author_avatar_url for each comment
   • Check response includes timestamp for new comments
   • Check old comments have timestamp: null

3. Verify Database Schema

Check if the timestamp column exists in the database:

SELECT column_name, data_type
FROM information_schema.columns 
WHERE table_name = 'song_comments';

Expected columns:

• id (uuid)
• song_id (uuid)
• author_id (uuid)
• body (text)
• timestamp (float) ← This is critical
• created_at (timestamp)

If timestamp column is missing:

ALTER TABLE song_comments ADD COLUMN timestamp FLOAT;

4. Check API Schema Compatibility

Verify that the API schema matches what the frontend expects:

API Schema (api/src/rehearsalhub/schemas/comment.py):

class SongCommentRead(BaseModel):
    id: uuid.UUID
    song_id: uuid.UUID
    body: str
    author_id: uuid.UUID
    author_name: str
    author_avatar_url: str | None  # ← Must be present
    timestamp: float | None         # ← Must be present
    created_at: datetime

Frontend Interface (web/src/pages/SongPage.tsx):

interface SongComment {
  id: string;
  song_id: string;
  body: string;
  author_id: string;
  author_name: string;
  author_avatar_url: string | null;  # ← Must match API
  created_at: string;
  timestamp: number | null;           # ← Must match API
}

5. Test Comment Creation Flow

Step-by-step test:

1. Play audio: Start playing a song and let it progress to a specific time (e.g., 30 seconds)
2. Create comment: Type a comment and click "Post"
3. Check console: Should see Creating comment with timestamp: 30.123
4. Check network: POST request should include {"body": "test", "timestamp": 30.123}
5. Check response: Should be 201 Created with comment data including timestamp
6. Check markers: Should see debug log Adding marker at time: 30.123
7. Visual check: Marker should appear on waveform at correct position

6. Common Issues and Fixes

Issue: No markers appear on waveform

Possible causes:

1. Timestamp is null: Old comments don't have timestamps
2. API not returning avatar_url: Check network response
3. TypeScript error: Check browser console
4. Waveform not ready: Check if isReady is true in useWaveform

Fixes:

• Ensure new comments are created with timestamps
• Verify API returns author_avatar_url
• Check TypeScript interface matches API response

Issue: Markers appear but no avatars

Possible causes:

1. API not returning avatar_url: Check network response
2. User has no avatar: Falls back to placeholder (expected)
3. Invalid avatar URL: Check network tab for 404 errors

Fixes:

• Verify author_avatar_url is included in API response
• Check user records have valid avatar URLs
• Ensure fallback placeholder works

Issue: Markers in wrong position

Possible causes:

1. Incorrect timestamp: Check what timestamp is sent to API
2. Waveform duration mismatch: Check wavesurfer.getDuration()
3. Position calculation error: Check useWaveform.ts

Fixes:

• Verify timestamp matches playhead position
• Check waveform duration is correct
• Debug position calculation

7. Database Migration Check

If comments fail to create with timestamps:

1. Check migration status:

# Check alembic version
docker-compose exec api alembic current

# Check if timestamp column exists
psql -U rehearsalhub -d rehearsalhub -c "\d song_comments"

2. Apply migration if needed:

# Run all pending migrations
docker-compose exec api alembic upgrade head

# Or apply specific migration
docker-compose exec api alembic upgrade 0004

3. Manual fix if migration fails:

ALTER TABLE song_comments ADD COLUMN timestamp FLOAT;

8. Verify Backend Code

Check that the backend properly handles the timestamp:

Router (api/src/rehearsalhub/routers/songs.py):

@router.post("/songs/{song_id}/comments")
async def create_comment(
    song_id: uuid.UUID,
    data: SongCommentCreate,  # ← Should include timestamp
    # ...
):
    comment = await repo.create(
        song_id=song_id, 
        author_id=current_member.id, 
        body=data.body, 
        timestamp=data.timestamp  # ← Should be passed
    )

Schema (api/src/rehearsalhub/schemas/comment.py):

class SongCommentCreate(BaseModel):
    body: str
    timestamp: float | None = None  # ← Must allow None for backward compatibility

Expected Behavior After Fix

1. ✅ New comments capture timestamp: When creating a comment while audio is playing, the current playhead position is captured
2. ✅ Markers show user avatars: Waveform markers display the comment author's avatar when available
3. ✅ Markers at correct position: Markers appear on waveform at the exact time the comment was created
4. ✅ Marker interaction works: Clicking markers scrolls comment section to corresponding comment
5. ✅ Backward compatibility: Old comments without timestamps still work (no markers shown)

Troubleshooting Checklist

• Check browser console for errors
• Verify network requests/response structure
• Confirm database has timestamp column
• Check API schema matches frontend interface
• Test comment creation with debug logs
• Verify marker positioning calculation
• Check avatar URL handling

Additional Debugging Tips

1. Add more debug logs: Temporarily add console.log statements to track data flow
2. Test with Postman: Manually test API endpoints to isolate frontend/backend issues
3. Check CORS: Ensure no CORS issues are preventing requests
4. Verify authentication: Ensure user is properly authenticated
5. Check waveform initialization: Ensure waveform is properly initialized before adding markers