Skip to main content

​
Overview

Lawn’s comment system is purpose-built for video review, enabling teams to provide precise, timestamped feedback directly on videos. Comments support threaded discussions and resolution tracking to manage the review process.

​
Timestamped Comments

Every comment is anchored to a specific moment in the video:

Precise Feedback

Comments are attached to exact timestamps (in seconds) for context-specific feedback

Automatic Sorting

Top-level comments are sorted by timestamp to follow the video timeline

Quick Navigation

Click a comment to jump directly to that moment in the video

Visual Markers

Comment markers appear on the playback timeline for easy reference

​
Comment Structure

Comments follow a two-level threading model:

​
Top-Level Comments

Top-level comments represent distinct pieces of feedback:
  • Anchored to a specific video timestamp
  • Can be marked as resolved or unresolved
  • Sorted chronologically by timestamp
  • Include author name, avatar, and creation time

​
Replies

Each top-level comment can have multiple replies:
  • Inherit the timestamp from the parent comment
  • Sorted by creation time (oldest first)
  • Support threaded discussions
  • Deleted when parent comment is deleted
The two-level threading model keeps discussions focused and prevents deeply nested reply chains that are hard to follow.

​
Creating Comments

Comments can be created through multiple access methods:
Team members with viewer role or higher can comment on any video in their projects. Comments include full user information from the team membership.

​
Comment Management

​
Editing Comments

Users can edit their own comments:
  • Only the comment text can be modified
  • Timestamp and author information remain unchanged
  • No edit history is tracked (follows simplicity philosophy)

​
Deleting Comments

Comment deletion follows role-based rules:
1

Own Comments

Users can delete their own comments at any time
2

Admin Override

Team admins can delete any comment on videos in their projects
3

Cascade Deletion

When a comment is deleted, all replies are automatically removed
4

Video Deletion

All comments are deleted when the parent video is removed
Deleting a comment removes all replies permanently. This action cannot be undone.

​
Resolution Workflow

Comments include a resolution system for tracking feedback completion:

​
Resolution States

Unresolved

Default state for new comments. Indicates feedback that needs to be addressed.

Resolved

Comment has been addressed or is no longer relevant. Visual indicator shows completion.

​
Resolution Permissions

Only team members with member role or higher can toggle comment resolution:
  • Viewers can comment but cannot mark comments as resolved
  • Resolution status helps track review progress
  • Resolved comments remain visible in the timeline
Resolution is a simple boolean toggle - there’s no need for complex workflow states. This follows Lawn’s philosophy of good defaults and minimal friction.

​
Threaded View

Comments are organized in a threaded view for easy navigation: 
// Comment thread structure
{
  _id: "comment-id",
  text: "This transition needs work",
  timestampSeconds: 45.2,
  userName: "Sarah Designer",
  userAvatarUrl: "https://...",
  resolved: false,
  replies: [
    {
      _id: "reply-id",
      text: "Agreed, I'll smooth it out",
      parentId: "comment-id",
      userName: "Alex Editor",
      _creationTime: 1234567890
    }
  ]
}

​
Comment Metadata

Each comment includes comprehensive information:

​
User Information

  • User Name: Display name of the commenter
  • Avatar URL: Profile picture for visual identification
  • User ID: Clerk authentication ID for ownership verification

​
Comment Data

  • Text Content: The actual comment message
  • Timestamp: Exact video position (in seconds with decimal precision)
  • Creation Time: When the comment was created
  • Parent ID: Reference to parent comment for replies
  • Resolved Status: Whether feedback has been addressed

​
Public Comment Visibility

Comments on public and shared videos use privacy-safe data:

Limited User Data

Only name and avatar are exposed, never user IDs or email addresses

Team Context Hidden

Team information is not included in public comment responses

​
Comment Queries

The comment system supports multiple query patterns:

​
By Video

Retrieve all comments for a specific video:
  • Requires video access permissions
  • Returns flat list sorted by timestamp
  • Includes all replies

​
By Timestamp Range

Query comments within a specific time range:
  • Useful for highlighting comments in the current playback section
  • Indexed by video ID and timestamp for fast lookups
  • Supports playback scrubbing features

​
Threaded View

Get comments organized with replies:
  • Top-level comments sorted by timestamp
  • Replies nested under parent comments
  • Replies sorted by creation time

​
Performance Optimizations

Comments are optimized for real-time collaboration:

​
Database Indexing

  • by_video: Fast queries for all comments on a video
  • by_video_and_timestamp: Range queries for playback position
  • by_parent: Efficient reply lookups

​
Optimistic Updates

  • New comments appear instantly in the UI
  • Resolution toggles feel immediate
  • Comment counts update in real-time
Comment operations are designed to be fast and non-blocking, following Lawn’s performance-first philosophy.

​
Comment Count Tracking

Video records include real-time comment counts:
  • Total count includes both comments and replies
  • Automatically updated when comments are added or removed
  • Displayed in video lists for engagement visibility
  • No separate counter table needed (calculated on query)

​
Integration with Video Workflow

Comments integrate with the video review workflow:
  • Unresolved comments indicate pending feedback
  • Resolution progress helps determine when to move videos to “Done” status
  • Comment activity drives team collaboration
  • Comment timestamps link directly to video moments
Encourage reviewers to use timestamps liberally - precise feedback saves time and reduces back-and-forth communication.

Build docs developers (and LLMs) love

Get started for freeTalk to us