Skip to main content

Comments & Review

The comments system in Scriptix enables collaborative review, feedback, and quality assurance for your transcripts. Add notes, request changes, discuss unclear sections, and track review progress—all within the transcript editor.

What Are Comments?​

Comments are annotations attached to specific text ranges in your transcript. They allow you to:

  • Flag Issues - Mark errors, unclear sections, or areas needing attention
  • Request Changes - Ask collaborators to review or revise specific parts
  • Provide Context - Explain background information or reasoning
  • Track Review - Monitor which sections need attention
  • Collaborate - Discuss transcript content with team members

Comment Characteristics​

  • Text-Based - Comments contain text notes and descriptions
  • Range-Linked - Each comment is attached to a specific word or text range via timestamps
  • Timestamped - Comments know their creation time and position in audio
  • User-Attributed - Comments show who created them (created_by_name)
  • Editable - You can modify your own comments
  • Deletable - You can remove your own comments when resolved

The Comments Panel​

Accessing Comments​

The comments panel appears on the right side of the transcript editor:

Location:

  • Right sidebar (1 column width)
  • Beside the main editor (6 columns)
  • Always visible on desktop
  • May collapse on smaller screens

Panel Contents:

  • List of all comments in the document
  • Each comment shows: author name, creation time, and text preview
  • Scrollable list for many comments

Comment List View​

Each comment in the panel displays:

John Doe                      3h
Please verify the speaker's
name at this location...      ✎

Information Shown:

  • Creator Name - Who wrote the comment (created_by_name)
  • Creation Time - When the comment was added (relative format: "3h", "2d", "1mo")
    • Uses formatDateAgo() utility for human-readable time
  • Comment Text - Preview truncated to 2 lines (line-clamp-2)
  • Edit Icon - Pencil icon (✎) to edit/delete the comment

Visual States:

  • Normal - White background with border and shadow
  • Selected - Blue border (border-blue-400) when clicked
  • Hover - Cursor pointer to indicate clickability

Navigating to Commented Text​

How It Works:

  1. Click any comment in the Comments panel
  2. The comment is selected (blue border appears)
  3. The transcript automatically highlights the commented text range
  4. Words within the comment's range show gray background (#dbdde3)

Implementation:

  • Clicking sets clickedComment in context state
  • All text nodes (leaves) check if their timestamp range overlaps with clickedComment.index_from and index_to
  • Matching words receive gray background highlighting

Visual Feedback:

  • Selected comment in panel: Blue border
  • Commented text in editor: Gray background (#dbdde3)
  • Click anywhere outside the comment to clear selection

Creating Comments​

Add comments to any part of your transcript:

How to Create a Comment​

Step 1: Select Text

  1. Click and drag to select the text you want to comment on
  2. Must select at least one word
  3. Selected word's start/stop timestamps are captured

Step 2: Open Text Style Toolbar 3. A floating toolbar appears near your selection 4. The toolbar includes formatting buttons: Bold, Italic, Underline, Strikethrough 5. Includes highlight color options 6. Comment button (💬 MessageCircle icon) on the right

Step 3: Click Comment Button 7. Click the Comment button (💬 icon) 8. If no text is selected, you'll see an error: "Please select the text to add comment to"

Step 4: Write Comment 9. A modal dialog appears with title "Comment Options" 10. Caption: "Edit the comment content or delete it" 11. Text input field for your comment 12. Type your comment text (required, cannot be empty) 13. Click "Save" or "Update" button

Comment Creation Tips​

Be Specific:

  • Select exactly the text you're commenting about
  • Include enough context in your selection
  • Write clear, actionable comment text

Good Comment Examples:

  • ✅ "Verify this product name—should it be 'DataSync Pro' instead?"
  • ✅ "Audio is unclear here. Please listen and confirm wording."
  • ✅ "This speaker is labeled incorrectly. This is actually John, not Mike."
  • ✅ "Technical term: verify if this should be 'API endpoint' not 'AP eye endpoint'"

Poor Comment Examples:

  • ❌ "Fix this" (too vague)
  • ❌ "???" (no information)
  • ❌ "Wrong" (doesn't explain what's wrong or what it should be)

When to Comment:

  • Uncertain about correct transcription
  • Need clarification from a colleague
  • Flagging sections for QA review
  • Requesting verification of technical terms
  • Noting audio quality issues
  • Marking sections that need speaker relabeling

Viewing Comments​

In the Comments Panel​

List Display:

  • All comments appear in a vertical list
  • Ordered chronologically (as returned by API)
  • Each comment is a separate card with border and shadow
  • Scrollable if many comments exist

Comment Card Information:

  • Top left: Creator name (bold, truncated if too long)
  • Top right: Relative creation time ("3h ago", "2 days ago")
  • Bottom: Comment text (truncated to 2 lines with ellipsis)
  • Edit icon: Pencil icon (PencilLine) in top right

Interaction:

  • Click anywhere on the comment card to select it
  • Selected comment shows blue border
  • Click pencil icon to open edit modal
  • Click outside comment to deselect

Highlighted Text in Editor​

When a comment is selected:

  • All words whose timestamps overlap with the comment range are highlighted
  • Highlighting uses gray background color: #dbdde3

Visual Priority:

  • Search highlights: Beige (#ffeeba) - highest priority
  • Comment highlights: Gray (#dbdde3) - medium priority
  • Mark highlights: Yellow/Pink - based on mark color
  • Current word: Blue (#0a8df8) - during playback

Editing Comments​

Update your own comments to clarify or correct information:

How to Edit​

Step 1: Find Your Comment

  1. Locate the comment in the Comments panel
  2. Look for the pencil icon (✎) in the top right

Step 2: Open Edit Modal 3. Click the pencil icon (PencilLine) 4. Modal opens with title "Comment Options" 5. Caption: "Edit the comment content or delete it"

Step 3: Modify Text 6. Current comment text appears in the input field (multiline textarea) 7. Edit the text as needed 8. Text must not be empty (validation enforced)

Step 4: Save Changes 9. Click "Update" button (shows "Updating..." while saving)

Result:

  • Success toast: "Comment updated successfully"
  • Comment text updates immediately in the panel
  • Position (index_from, index_to) remains unchanged
  • Modal closes automatically
  • Comments list refreshes

Validation:

  • Empty comments are not allowed
  • Toast error: "Comment is empty"
  • Must have at least some text content

When to Edit Comments​

  • Clarify - Make the comment more specific or detailed
  • Correct - Fix typos or errors in your comment text
  • Update - Add new information or context discovered during review
  • Resolve Partially - Note that some issues are fixed but others remain

Example:

  • Original: "Check this section"
  • Edited: "Check this section—verified product name is correct, but verify the version number (should be 2.5)"

Deleting Comments​

Remove comments that are no longer needed:

How to Delete​

Step 1: Open Edit Modal

  1. Click the pencil icon on the comment you want to delete
  2. Modal opens showing the comment text

Step 2: Click Delete Button 3. Click the red "Delete" button in the modal footer 4. Button styled with variant="danger" (red/destructive)

Step 3: Confirm Deletion

Result:

  • Success toast: "Comment deleted successfully"
  • Comment is permanently removed from the panel
  • Cannot be recovered after deletion
  • Modal closes automatically
  • Comments list refreshes

When to Delete Comments​

  • Resolved - Issue has been fixed and verified
  • No Longer Relevant - Comment doesn't apply anymore after edits
  • Duplicate - You created multiple comments about the same thing
  • Mistake - Comment added in error

Note: Deleting a comment doesn't undo any edits made to the transcript based on that comment. It only removes the annotation.

Comment Workflow Examples​

Solo Review Workflow​

When reviewing your own transcript:

Use Comments to:

  1. Flag uncertainties while doing initial review
  2. Mark sections to revisit later
  3. Note audio quality issues for reference
  4. Track progress through the document

Workflow:

  1. First pass: Skim transcript, add comments for unclear sections
  2. Second pass: Review each comment in the panel
  3. Click comments to jump to each section
  4. Listen to audio and make corrections
  5. Delete resolved comments as you go
  6. Final pass: Verify all comments are addressed

Team Collaboration Workflow​

When working with others:

Reviewer Workflow:

  1. Read through the transcript carefully
  2. Select text and add comments for issues, questions, or suggestions
  3. Be specific and constructive in comment text
  4. Submit/save the document for the transcriptionist

Transcriptionist Workflow:

  1. Open the transcript with comments
  2. Review each comment in the Comments panel (right sidebar)
  3. Click comment to navigate to that section
  4. Listen to the audio at that timestamp
  5. Make necessary changes to the transcript
  6. Delete comment when issue is resolved

Quality Assurance Workflow:

  1. QA reviewer adds comments for errors found
  2. Transcriptionist reviews comments and fixes issues
  3. Transcriptionist deletes comments as they're resolved
  4. QA reviewer re-checks to confirm all comments are gone
  5. Transcript marked as final when no comments remain

Client Review Workflow​

When sharing with clients for feedback:

Internal Team:

  1. Complete initial transcription
  2. Internal review with comments
  3. Resolve all internal comments
  4. Verify no comments remain

Client Review: 5. Share transcript with client (via share link) 6. Client adds comments for corrections or questions 7. Team reviews client comments 8. Team addresses each comment and makes corrections 9. Team deletes comments as issues are resolved 10. Re-share updated version with client 11. Client confirms, all comments resolved

Comment Best Practices​

Writing Effective Comments​

Be Clear and Specific:

  • Explain exactly what the issue is
  • Suggest a solution if possible
  • Provide context or reasoning

Examples:

✅ Good Comments:

  • "Please verify: is this 'Smith' or 'Smythe'? Audio is unclear at 2:35."
  • "Technical term here: should be 'API endpoint' not 'AP eye endpoint'"
  • "Speaker label incorrect—this is Sarah speaking, not John."
  • "Background noise makes this word inaudible. Listen at [00:05:23] to confirm."
  • "Acronym: verify if 'SLA' or 'SLS' was said here."

❌ Poor Comments:

  • "Wrong" (what's wrong? what should it be?)
  • "???" (not helpful to anyone)
  • "Fix" (fix what? how?)
  • "Bad" (what's bad? be specific)

Using Comments Efficiently​

1. Comment While Reviewing

  • Don't stop to fix every issue immediately during first pass
  • Add comments as you find problems
  • Come back later to address all comments at once
  • More efficient than constant context-switching

2. Prioritize Comments

  • Use clear language to indicate severity
  • "URGENT:" for critical errors affecting meaning
  • "Minor:" for low-priority typos or formatting
  • "Question:" for uncertainties needing clarification

3. Reference Timestamps

  • Include timestamps in comments when helpful
  • "Check audio at [00:05:23]—unclear word here"
  • "At [00:15:30], verify if this is 'revenue' or 'avenue'"

4. Clean Up Resolved Comments

  • Delete comments immediately after fixing issues
  • Keeps the comments panel clean and focused
  • Makes it easy to see what still needs attention
  • Empty comments panel = fully reviewed transcript

Collaboration Etiquette​

Be Constructive:

  • Focus on improving the transcript quality
  • Use professional, respectful language
  • Assume good intentions from collaborators
  • Provide helpful suggestions, not just criticism

Be Responsive:

  • Address comments promptly
  • Delete resolved comments to show progress
  • Acknowledge and thank collaborators for feedback

Be Organized:

  • Use consistent comment formats
  • One issue per comment (don't combine unrelated items)
  • Update or delete outdated comments
  • Keep comment text concise but complete

Comment Limitations​

Current Limitations​

Cannot:

  • Thread replies - Comments are standalone, no conversation threads
  • Assign comments - No way to assign a comment to a specific user
  • Set priorities - No built-in priority levels or urgency flags
  • Set statuses - No "resolved" vs "open" status (only delete or keep)
  • Filter comments - Cannot filter by author, date, or type
  • Search comments - No search within comment text
  • Sort comments - Fixed chronological order from API
  • Mention users - No @mention or notification system
  • Attach files - Text-only, no image or file attachments
  • See edit history - No version history for comment edits
  • Permission control - All collaborators can edit/delete any comments

Workarounds:

  • Priorities: Use prefixes like "[URGENT]", "[MINOR]", "[QUESTION]"
  • Assignment: Include name in comment: "@Sarah: please verify this section"
  • Status: Use prefixes like "[IN PROGRESS]", "[DONE]" before deleting
  • Categories: Use tags like "[TECH]", "[SPEAKER]", "[AUDIO]", "[QA]"

Comments and Document State​

Comments and Auto-Save​

  • Comments are separate from transcript content
  • Creating/editing/deleting comments doesn't trigger transcript auto-save
  • Comments save independently to their own endpoints
  • Transcript and comments use different React Query cache keys

Comments and Export​

  • Comments are NOT included in exports
  • Exported files (DOCX, TXT, PDF, SRT, VTT) contain only transcript text
  • Comments are for internal review and collaboration only
  • They never appear in final output

If you need comments in exports:

  • Manually copy comment text into the transcript itself as notes
  • Or compile comments into a separate review document
  • Or screenshot the comments panel for documentation

Comments and Sharing​

When sharing transcripts:

  • Shared access: Collaborators with edit access can likely add/edit/delete comments
  • Read-only access: Viewers cannot add comments
  • Session-based: Comments are tied to specific session and document IDs

Note: Specific permissions may vary based on your organization's settings.

Troubleshooting​

Cannot Create Comment​

Issue: Comment button doesn't work or modal doesn't appear

Possible Causes:

  • Text not properly selected
  • startStopWord is null (no word timing data)
  • JavaScript error or browser issue

Solutions:

  1. Ensure text is selected (highlighted in blue or gray)
  2. Try selecting different text (a clear word with timing data)
  3. Refresh the page and try again
  4. Check browser console for errors

Comment Text is Empty/Cannot Save​

Issue: Getting error "Comment is empty" when trying to save

Cause: Comment text field is empty or contains only whitespace

Solution:

  • Enter some text in the comment field
  • Text is required, cannot be empty
  • Even after editing, text must remain non-empty

Cannot See Comments​

Issue: Comments panel is empty, but comments should exist

Possible Causes:

  • Comments panel failed to load
  • No comments actually exist yet
  • API error when fetching comments

Solutions:

  1. Check if "Loading comments..." appears (data is fetching)
  2. Refresh the page to retry the API call
  3. Verify you're viewing the correct document
  4. Check browser console for API errors

Comment Not Highlighting Text​

Issue: Clicking a comment doesn't highlight the text in the editor

Possible Causes:

  • Text was deleted or heavily edited after comment was created
  • Comment's index_from/index_to no longer match any words
  • UI rendering issue

Solutions:

  1. Refresh the page
  2. Check if the commented text still exists
  3. If text was deleted, delete the comment (it's orphaned)
  4. Manually search for similar text nearby

Cannot Edit/Delete Comment​

Issue: Pencil icon doesn't appear or doesn't work

Possible Causes:

  • You're not the comment creator (permission issue)
  • JavaScript error
  • Modal already open

Solutions:

  1. Verify you created the comment (check created_by_name)
  2. Close any open modals first
  3. Refresh the page
  4. Check browser console for errors

Frequently Asked Questions​

Can I see who created each comment?​

Yes, each comment displays the creator's name (created_by_name) at the top of the comment card.

Can I reply to comments?​

No, there's no threading or reply system. Comments are standalone. However, you can edit your own comment to add responses, or create a new comment nearby.

Can others edit my comments?​

Based on the current implementation, each user can only edit and delete their own comments. The edit icon is shown for all comments, but editing should only affect your own.

Do comments affect the transcript?​

No, comments are annotations only. They don't change the transcript text. You must manually make edits based on the comments.

Are comments included when I export the transcript?​

No, comments are for internal review and collaboration only. They are not included in any export format (DOCX, TXT, PDF, SRT, VTT).

Can I filter or search comments?​

Currently, no. All comments appear in the order returned by the API. There's no built-in filtering, searching, or sorting.

How many comments can I add?​

There's no stated limit. Add as many comments as needed for thorough review.

Can I use comments on shared transcripts?​

Yes, if you have edit/collaboration access to a shared transcript, you can add, edit, and delete comments. Read-only viewers cannot add comments.

What happens to comments if I delete the transcript?​

Comments are tied to the document and session. If the document is deleted, comments are likely deleted as well.

Can I see when a comment was last edited?​

No, there's no edit timestamp. You only see the original creation time.

Do comments include timestamps for audio position?​

Yes! Comments store index_from and index_to which are millisecond timestamps. This links the comment to a specific audio position and text range.

Next Steps​

Enhance your review workflow:

Start collaborating! Add comments to flag issues and improve transcript quality.