Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

feat(video-learning): add timestamped watching marks

XZH7e45ab851e10
diff --git a/deeptutor/api/routers/video_learning.py b/deeptutor/api/routers/video_learning.py
index 0dd5e8a1b..377784d16 100644
--- a/deeptutor/api/routers/video_learning.py
+++ b/deeptutor/api/routers/video_learning.py
@@ -17,14 +17,20 @@ from deeptutor.services.notebook.service import NotebookCorruptedError
from deeptutor.video_learning import (
TimedMediaError,
TimedMediaNotFound,
+ create_mark,
+ delete_mark,
+ get_mark,
get_timed_media_store,
invidious_account,
load_video_learning_settings,
+ marks_list,
material_with_playback,
refresh_invidious_transcript,
resolve_material,
save_video_learning_settings,
+ suggest_marks,
test_invidious_connection,
+ update_mark,
)
from deeptutor.video_learning import notes as video_notes
@@ -55,6 +61,33 @@ class UpdateVideoNoteRequest(BaseModel):
body: str = Field(min_length=1, max_length=20_000)
+class MarkCreateRequest(BaseModel):
+ kind: str = Field(min_length=1, max_length=32)
+ start_seconds: float = Field(ge=0, le=24 * 60 * 60)
+ end_seconds: float = Field(ge=0, le=24 * 60 * 60)
+ start_locator: int = Field(default=0, ge=0)
+ end_locator: int = Field(default=0, ge=0)
+ quote: str = Field(default="", max_length=4000)
+ note: str = Field(default="", max_length=2000)
+ metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class MarkPatchRequest(BaseModel):
+ kind: str | None = Field(default=None, max_length=32)
+ start_seconds: float | None = Field(default=None, ge=0, le=24 * 60 * 60)
+ end_seconds: float | None = Field(default=None, ge=0, le=24 * 60 * 60)
+ start_locator: int | None = Field(default=None, ge=0)
+ end_locator: int | None = Field(default=None, ge=0)
+ quote: str | None = Field(default=None, max_length=4000)
+ note: str | None = Field(default=None, max_length=2000)
+ reviewed: bool | None = None
+ metadata: dict[str, Any] | None = None
+
+
+class MarkSuggestionRequest(BaseModel):
+ time_seconds: float = Field(default=0.0, ge=0, le=24 * 60 * 60)
+
+
class YouTubeSettings(BaseModel):
transcript_provider: str = Field(default="youtube_transcript_api", max_length=64)
@@ -282,6 +315,76 @@ async def delete_video_note(material_id: str, note_id: str) -> dict[str, str]:
raise _note_error(exc) from exc
[email protected]("/materials/{material_id}/marks")
+async def list_video_marks(material_id: str) -> list[dict[str, Any]]:
+ try:
+ material = get_timed_media_store().get(material_id)
+ return marks_list(material)
+ except Exception as exc:
+ raise _http_error(exc) from exc
+
+
[email protected]("/materials/{material_id}/marks/{mark_id}")
+async def get_video_mark(material_id: str, mark_id: str) -> dict[str, Any]:
+ try:
+ material = get_timed_media_store().get(material_id)
+ return get_mark(material, mark_id)
+ except Exception as exc:
+ raise _http_error(exc) from exc
+
+
[email protected]("/materials/{material_id}/marks", status_code=201)
+async def create_video_mark(material_id: str, payload: MarkCreateRequest) -> dict[str, Any]:
+ try:
+ store = get_timed_media_store()
+ with store.lock(material_id):
+ material = store.get(material_id, lock_held=True)
+ mark = create_mark(material, payload.model_dump())
+ store.save(material)
+ return mark
+ except Exception as exc:
+ raise _http_error(exc) from exc
+
+
[email protected]("/materials/{material_id}/marks/{mark_id}")
+async def update_video_mark(
+ material_id: str, mark_id: str, payload: MarkPatchRequest
+) -> dict[str, Any]:
+ try:
+ store = get_timed_media_store()
+ fields = payload.model_dump(exclude_unset=True)
+ with store.lock(material_id):
+ material = store.get(material_id, lock_held=True)
+ mark = update_mark(material, mark_id, fields)
+ store.save(material)
+ return mark
+ except Exception as exc:
+ raise _http_error(exc) from exc
+
+
[email protected]("/materials/{material_id}/marks/{mark_id}")
+async def delete_video_mark(material_id: str, mark_id: str) -> dict[str, bool]:
+ try:
+ store = get_timed_media_store()
+ with store.lock(material_id):
+ material = store.get(material_id, lock_held=True)
+ delete_mark(material, mark_id)
+ store.save(material)
+ return {"ok": True}
+ except Exception as exc:
+ raise _http_error(exc) from exc
+
+
[email protected]("/materials/{material_id}/mark-suggestions")
+async def suggest_video_marks(material_id: str, payload: MarkSuggestionRequest) -> dict[str, Any]:
+ try:
+ material = get_timed_media_store().get(material_id)
+ suggestions = await suggest_marks(material, payload.time_seconds)
+ return {"suggestions": suggestions}
+ except Exception as exc:
+ raise _http_error(exc) from exc
+
+
def _vtt_timestamp(value: Any) -> str:
milliseconds = int(round(max(0.0, float(value or 0)) * 1000))
hours, remainder = divmod(milliseconds, 3_600_000)
diff --git a/deeptutor/video_learning/__init__.py b/deeptutor/video_learning/__init__.py
index 763bd39f6..890478cf3 100644
--- a/deeptutor/video_learning/__init__.py
+++ b/deeptutor/video_learning/__init__.py
@@ -7,6 +7,18 @@ from .invidious_account import (
invidious_account_status,
invidious_redirect_uri,
)
+from .marks import (
+ MARK_AUTHORS,
+ MARK_KINDS,
+ MarkNotFound,
+ create_mark,
+ delete_mark,
+ get_mark,
+ marks_list,
+ normalize_mark,
+ suggest_marks,
+ update_mark,
+)
from .service import (
PROVIDER_RESOLVERS,
ProviderResolution,
@@ -46,4 +58,14 @@ __all__ = [
"resolve_material",
"save_video_learning_settings",
"test_invidious_connection",
+ "MARK_AUTHORS",
+ "MARK_KINDS",
+ "MarkNotFound",
+ "create_mark",
+ "delete_mark",
+ "get_mark",
+ "marks_list",
+ "normalize_mark",
+ "suggest_marks",
+ "update_mark",
]
diff --git a/deeptutor/video_learning/marks.py b/deeptutor/video_learning/marks.py
new file mode 100644
index 000000000..28ffb44c5
--- /dev/null
+++ b/deeptutor/video_learning/marks.py
@@ -0,0 +1,409 @@
+"""Private learning marks attached to a timed-media material."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import hashlib
+import json
+import re
+from typing import Any
+
+from deeptutor.video_learning.service import TimedMediaError, TimedMediaNotFound
+
+MARK_KINDS = frozenset({"key_point", "question", "review"})
+MARK_AUTHORS = frozenset({"user", "assistant"})
+MARK_SOURCES = frozenset({"immersive"})
+MAX_MARKS_PER_MATERIAL = 500
+MAX_QUOTE_CHARS = 4000
+MAX_NOTE_CHARS = 2000
+MAX_SUGGESTIONS = 5
+NEARBY_WINDOW_SECONDS = 60.0
+
+_JSON_FENCE = re.compile(r"^```(?:json)?\s*|\s*```$", re.IGNORECASE)
+
+
+class MarkNotFound(TimedMediaNotFound):
+ """A mark does not belong to the requested material."""
+
+
+def utcnow() -> str:
+ """Return the current UTC timestamp formatted as ISO-8601 string."""
+ return datetime.now(timezone.utc).isoformat()
+
+
+def _clip_text(value: Any, limit: int) -> str:
+ text = re.sub(r"\s+", " ", str(value or "")).strip()
+ return text[:limit]
+
+
+def _as_seconds(value: Any) -> float:
+ try:
+ seconds = float(value)
+ except (TypeError, ValueError) as exc:
+ raise TimedMediaError("Mark timestamps must be numbers.") from exc
+ if seconds < 0 or seconds > 24 * 60 * 60:
+ raise TimedMediaError("Mark timestamps are outside the allowed range.")
+ return seconds
+
+
+def _duration_seconds(material: dict[str, Any]) -> float:
+ source = material.get("source") if isinstance(material.get("source"), dict) else {}
+ metadata = material.get("metadata") if isinstance(material.get("metadata"), dict) else {}
+ for row in (source, metadata):
+ try:
+ duration = float(row.get("duration_seconds") or 0)
+ except (TypeError, ValueError):
+ duration = 0.0
+ if duration > 0:
+ return duration
+ return 0.0
+
+
+def _segments(material: dict[str, Any]) -> list[dict[str, Any]]:
+ rows = material.get("segments")
+ return [row for row in rows if isinstance(row, dict)] if isinstance(rows, list) else []
+
+
+def _cues(material: dict[str, Any]) -> list[dict[str, Any]]:
+ transcript = material.get("transcript") if isinstance(material.get("transcript"), dict) else {}
+ rows = transcript.get("cues")
+ return [row for row in rows if isinstance(row, dict)] if isinstance(rows, list) else []
+
+
+def locators_for_range(material: dict[str, Any], start: float, end: float) -> tuple[int, int]:
+ """Find start and end segment locators overlapping the specified time span."""
+ overlapping = [
+ row
+ for row in _segments(material)
+ if float(row.get("end") or 0) >= start and float(row.get("start") or 0) <= end
+ ]
+ if not overlapping:
+ return 0, 0
+ start_locator = int(overlapping[0].get("locator") or 0)
+ end_locator = int(overlapping[-1].get("locator") or start_locator)
+ return max(0, start_locator), max(0, end_locator)
+
+
+def quote_for_range(material: dict[str, Any], start: float, end: float) -> str:
+ """Concatenate subtitle cue text within the specified time span."""
+ selected = [
+ str(row.get("text") or "").strip()
+ for row in _cues(material)
+ if str(row.get("text") or "").strip()
+ and float(row.get("end") or 0) >= start
+ and float(row.get("start") or 0) <= end
+ ]
+ return _clip_text(" ".join(selected), MAX_QUOTE_CHARS)
+
+
+def nearby_cues(
+ material: dict[str, Any], time_seconds: float, window: float = NEARBY_WINDOW_SECONDS
+) -> list[dict[str, Any]]:
+ """Return subtitle cues whose start is within the window of time_seconds."""
+ return [
+ row for row in _cues(material) if abs(float(row.get("start") or 0) - time_seconds) <= window
+ ]
+
+
+def current_segment(material: dict[str, Any], time_seconds: float) -> dict[str, Any] | None:
+ """Find the material segment containing time_seconds."""
+ return next(
+ (
+ row
+ for row in _segments(material)
+ if float(row.get("start") or 0) <= time_seconds <= float(row.get("end") or 0)
+ ),
+ None,
+ )
+
+
+def marks_list(material: dict[str, Any]) -> list[dict[str, Any]]:
+ """Return the mutable marks list in material learning state."""
+ learning = material.setdefault("learning", {})
+ marks = learning.get("marks")
+ if not isinstance(marks, list):
+ marks = []
+ learning["marks"] = marks
+ return marks
+
+
+def get_mark(material: dict[str, Any], mark_id: str) -> dict[str, Any]:
+ """Retrieve a mark by ID from the material or raise MarkNotFound."""
+ for mark in marks_list(material):
+ if isinstance(mark, dict) and str(mark.get("mark_id") or "") == mark_id:
+ return mark
+ raise MarkNotFound("Timed media mark was not found.")
+
+
+def normalize_mark(
+ material: dict[str, Any],
+ payload: dict[str, Any],
+ *,
+ existing: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+ """Validate and normalize mark fields for creation or update."""
+ kind = str(payload.get("kind") or (existing or {}).get("kind") or "").strip()
+ if kind not in MARK_KINDS:
+ raise TimedMediaError("Mark kind must be key_point, question, or review.")
+ start = _as_seconds(
+ payload["start_seconds"]
+ if "start_seconds" in payload
+ else (existing or {}).get("start_seconds", 0)
+ )
+ end = _as_seconds(
+ payload["end_seconds"]
+ if "end_seconds" in payload
+ else (existing or {}).get("end_seconds", start)
+ )
+ if end < start:
+ raise TimedMediaError("Mark end must be at or after the start time.")
+ duration = _duration_seconds(material)
+ if duration > 0:
+ if start > duration:
+ raise TimedMediaError("Mark start is beyond the video duration.")
+ end = min(end, duration)
+
+ derived_start, derived_end = locators_for_range(material, start, end)
+ start_locator = payload.get(
+ "start_locator", (existing or {}).get("start_locator", derived_start)
+ )
+ end_locator = payload.get("end_locator", (existing or {}).get("end_locator", derived_end))
+ try:
+ start_locator = max(0, int(start_locator or 0))
+ end_locator = max(0, int(end_locator or 0))
+ except (TypeError, ValueError) as exc:
+ raise TimedMediaError("Mark locators must be integers.") from exc
+ if start_locator == 0:
+ start_locator = derived_start
+ if end_locator == 0:
+ end_locator = derived_end or start_locator
+
+ quote = payload.get("quote")
+ if quote is None:
+ quote = (existing or {}).get("quote") or quote_for_range(material, start, end)
+ note = payload.get("note")
+ if note is None:
+ note = (existing or {}).get("note") or ""
+ author = str(payload.get("author") or (existing or {}).get("author") or "user")
+ if author not in MARK_AUTHORS:
+ raise TimedMediaError("Mark author must be user or assistant.")
+ source = str(payload.get("source") or (existing or {}).get("source") or "immersive")
+ if source not in MARK_SOURCES:
+ raise TimedMediaError("Mark source must be immersive.")
+
+ raw_metadata = payload.get("metadata", (existing or {}).get("metadata") or {})
+ if raw_metadata is None:
+ raw_metadata = {}
+ if not isinstance(raw_metadata, dict):
+ raise TimedMediaError("Mark metadata must be an object.")
+ metadata = dict(raw_metadata)
+ if len(metadata) > 16:
+ raise TimedMediaError("Mark metadata has too many fields.")
+ if len(json.dumps(metadata, ensure_ascii=False, default=str)) > 4000:
+ raise TimedMediaError("Mark metadata is too large.")
+
+ stamp = utcnow()
+ mark_id = str((existing or {}).get("mark_id") or payload.get("mark_id") or "")
+ if not re.fullmatch(r"[0-9a-f]{16,64}", mark_id or ""):
+ seed = f"{material.get('material_id')}-{kind}-{start}-{end}-{stamp}"
+ mark_id = hashlib.sha256(seed.encode()).hexdigest()[:24]
+ mark = {
+ "mark_id": mark_id,
+ "kind": kind,
+ "start_seconds": start,
+ "end_seconds": end,
+ "start_locator": start_locator,
+ "end_locator": end_locator,
+ "quote": _clip_text(quote, MAX_QUOTE_CHARS),
+ "note": _clip_text(note, MAX_NOTE_CHARS),
+ "author": author,
+ "source": source,
+ "metadata": metadata,
+ "created_at": str((existing or {}).get("created_at") or stamp),
+ "updated_at": stamp,
+ }
+ reviewed_at = payload.get("reviewed_at", (existing or {}).get("reviewed_at"))
+ if payload.get("reviewed") is True:
+ reviewed_at = stamp
+ if payload.get("reviewed") is False:
+ reviewed_at = None
+ if reviewed_at:
+ mark["reviewed_at"] = str(reviewed_at)
+ return mark
+
+
+def create_mark(material: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+ """Create a new mark on the material."""
+ marks = marks_list(material)
+ if len(marks) >= MAX_MARKS_PER_MATERIAL:
+ raise TimedMediaError("This video already has the maximum number of marks.")
+ mark = normalize_mark(material, payload)
+ marks.append(mark)
+ return mark
+
+
+def update_mark(material: dict[str, Any], mark_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+ """Update fields on an existing mark."""
+ if not payload:
+ raise TimedMediaError("No mark fields to update.")
+ current = get_mark(material, mark_id)
+ updated = normalize_mark(material, payload, existing=current)
+ marks = marks_list(material)
+ for index, row in enumerate(marks):
+ if isinstance(row, dict) and str(row.get("mark_id") or "") == mark_id:
+ marks[index] = updated
+ return updated
+ raise MarkNotFound("Timed media mark was not found.")
+
+
+def delete_mark(material: dict[str, Any], mark_id: str) -> dict[str, Any]:
+ """Delete a mark from the material by mark_id."""
+ marks = marks_list(material)
+ for index, row in enumerate(marks):
+ if isinstance(row, dict) and str(row.get("mark_id") or "") == mark_id:
+ return marks.pop(index)
+ raise MarkNotFound("Timed media mark was not found.")
+
+
+def _parse_json_array(text: str) -> list[Any]:
+ raw = _JSON_FENCE.sub("", (text or "").strip())
+ start = raw.find("[")
+ end = raw.rfind("]")
+ if start < 0 or end <= start:
+ return []
+ try:
+ payload = json.loads(raw[start : end + 1])
+ except json.JSONDecodeError:
+ return []
+ return payload if isinstance(payload, list) else []
+
+
+def _public_suggestion(material: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any] | None:
+ try:
+ mark = normalize_mark(material, {**payload, "author": "assistant"})
+ except TimedMediaError:
+ return None
+ mark.pop("mark_id", None)
+ mark["quote"] = quote_for_range(material, mark["start_seconds"], mark["end_seconds"])
+ if not mark["quote"]:
+ return None
+ mark.pop("created_at", None)
+ mark.pop("updated_at", None)
+ mark.pop("reviewed_at", None)
+ return mark
+
+
+def heuristic_suggestions(material: dict[str, Any], time_seconds: float) -> list[dict[str, Any]]:
+ """Generate heuristic candidate marks based on the current segment or nearby cues."""
+ segment = current_segment(material, time_seconds)
+ if segment is None:
+ nearby = nearby_cues(material, time_seconds)
+ if not nearby:
+ return []
+ start = float(nearby[0].get("start") or time_seconds)
+ end = float(nearby[-1].get("end") or time_seconds)
+ text = " ".join(str(row.get("text") or "") for row in nearby)
+ else:
+ start = float(segment.get("start") or time_seconds)
+ end = float(segment.get("end") or time_seconds)
+ text = str(segment.get("text") or "")
+ candidates: list[dict[str, Any]] = [
+ {
+ "kind": "key_point",
+ "start_seconds": start,
+ "end_seconds": max(start, end),
+ "quote": text,
+ "note": "",
+ }
+ ]
+ if "?" in text or "?" in text:
+ candidates.append(
+ {
+ "kind": "question",
+ "start_seconds": start,
+ "end_seconds": max(start, end),
+ "quote": text,
+ "note": "",
+ }
+ )
+ return [
+ suggestion
+ for suggestion in (
+ _public_suggestion(material, {**row, "author": "assistant"})
+ for row in candidates[:MAX_SUGGESTIONS]
+ )
+ if suggestion is not None
+ ]
+
+
+async def suggest_marks(material: dict[str, Any], time_seconds: float) -> list[dict[str, Any]]:
+ """Generate candidate marks without writing any of them."""
+ segment = current_segment(material, time_seconds)
+ nearby = nearby_cues(material, time_seconds)
+ if not segment and not nearby:
+ return []
+ transcript = "\n".join(
+ f"[{float(row.get('start') or 0):.1f}-{float(row.get('end') or 0):.1f}] {row.get('text', '')}"
+ for row in nearby[:40]
+ )
+ prompt = (
+ "Extract up to 5 learning marks from this video excerpt. Return JSON only: "
+ '[{"kind":"key_point|question|review","start_seconds":number,"end_seconds":number,'
+ '"quote":"verbatim subtitle span","note":"optional short note"}]. '
+ "Use kind=key_point for core claims, question for unclear or asked points, and "
+ "review for items the learner should revisit. Keep quotes short.\n"
+ f"Current time: {time_seconds:.1f}\n"
+ f"Current segment: {json.dumps(segment or {}, ensure_ascii=False)}\n"
+ f"Nearby transcript:\n{transcript}"
+ )
+ try:
+ from deeptutor.services.llm import complete
+
+ raw = await complete(
+ prompt,
+ system_prompt=(
+ "You help a learner mark a video. Reply with a JSON array and no markdown. "
+ "Do not invent timestamps outside the supplied transcript."
+ ),
+ temperature=0.2,
+ max_tokens=800,
+ )
+ parsed = _parse_json_array(str(raw or ""))
+ except Exception:
+ parsed = []
+ suggestions: list[dict[str, Any]] = []
+ for row in parsed:
+ if not isinstance(row, dict):
+ continue
+ suggestion = _public_suggestion(material, row)
+ if suggestion is not None:
+ suggestions.append(suggestion)
+ if len(suggestions) >= MAX_SUGGESTIONS:
+ break
+ return suggestions or heuristic_suggestions(material, time_seconds)
+
+
+__all__ = [
+ "MARK_AUTHORS",
+ "MARK_KINDS",
+ "MARK_SOURCES",
+ "MAX_MARKS_PER_MATERIAL",
+ "MAX_NOTE_CHARS",
+ "MAX_QUOTE_CHARS",
+ "MAX_SUGGESTIONS",
+ "NEARBY_WINDOW_SECONDS",
+ "MarkNotFound",
+ "create_mark",
+ "current_segment",
+ "delete_mark",
+ "get_mark",
+ "heuristic_suggestions",
+ "locators_for_range",
+ "marks_list",
+ "nearby_cues",
+ "normalize_mark",
+ "quote_for_range",
+ "suggest_marks",
+ "update_mark",
+ "utcnow",
+]
diff --git a/tests/video_learning/test_marks.py b/tests/video_learning/test_marks.py
new file mode 100644
index 000000000..9d5f695c5
--- /dev/null
+++ b/tests/video_learning/test_marks.py
@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+import pytest
+
+from deeptutor.api.routers import video_learning
+from deeptutor.video_learning import service
+from deeptutor.video_learning.marks import (
+ create_mark,
+ delete_mark,
+ heuristic_suggestions,
+ normalize_mark,
+ suggest_marks,
+ update_mark,
+)
+
+
+class _Paths:
+ def __init__(self, root: Path) -> None:
+ self.root = root
+
+ def get_workspace_feature_dir(self, feature: str) -> Path:
+ assert feature == "timed_media"
+ return self.root / feature
+
+
+def client_and_store(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> tuple[TestClient, service.TimedMediaStore]:
+ monkeypatch.setattr(service, "get_current_path_service", lambda: _Paths(tmp_path))
+ app = FastAPI()
+ app.include_router(video_learning.router, prefix="/api/video-learning")
+ return TestClient(app), service.get_timed_media_store()
+
+
+def _material(store: service.TimedMediaStore, *, duration: float = 120) -> dict:
+ material = {
+ "version": 1,
+ "type": "timed_media",
+ "material_id": service.material_id_for("dQw4w9WgXcQ"),
+ "created_at": "2026-01-01T00:00:00+00:00",
+ "source": {
+ "provider": "youtube",
+ "video_id": "dQw4w9WgXcQ",
+ "url": "https://youtu.be/dQw4w9WgXcQ",
+ },
+ "metadata": {"title": "Demo", "duration_seconds": duration},
+ "transcript": {
+ "status": "ready",
+ "cues": [
+ {"start": 10, "end": 18, "text": "Gradient descent finds a local minimum."},
+ {"start": 18, "end": 30, "text": "Why does the learning rate matter?"},
+ {"start": 40, "end": 55, "text": "This example is worth reviewing later."},
+ ],
+ },
+ "segments": [
+ {
+ "locator": 1,
+ "start": 10,
+ "end": 30,
+ "text": "Gradient descent finds a local minimum. Why does the learning rate matter?",
+ },
+ {
+ "locator": 2,
+ "start": 40,
+ "end": 55,
+ "text": "This example is worth reviewing later.",
+ },
+ ],
+ "learning": {"last_position": 0},
+ }
+ return store.save(material)
+
+
+def test_mark_range_clamps_and_snapshots_quote(tmp_path: Path) -> None:
+ store = service.TimedMediaStore(root=tmp_path / "timed_media")
+ material = _material(store)
+ mark = create_mark(
+ material,
+ {
+ "kind": "key_point",
+ "start_seconds": 10,
+ "end_seconds": 400,
+ "quote": "keep this quote",
+ },
+ )
+ assert mark["end_seconds"] == 120
+ assert mark["quote"] == "keep this quote"
+ assert mark["start_locator"] == 1
+ assert mark["source"] == "immersive"
+ assert mark["metadata"] == {}
+
+
+def test_mark_updates_and_deletion_are_material_scoped(tmp_path: Path) -> None:
+ store = service.TimedMediaStore(root=tmp_path / "timed_media")
+ material = _material(store)
+ mark = create_mark(material, {"kind": "review", "start_seconds": 40, "end_seconds": 55})
+ updated = update_mark(material, mark["mark_id"], {"note": "rewatch", "reviewed": True})
+ assert updated["reviewed_at"]
+ assert delete_mark(material, mark["mark_id"])["mark_id"] == mark["mark_id"]
+ with pytest.raises(service.TimedMediaNotFound):
+ delete_mark(material, mark["mark_id"])
+
+
+def test_point_bookmark_and_reversed_ranges(tmp_path: Path) -> None:
+ store = service.TimedMediaStore(root=tmp_path / "timed_media")
+ material = _material(store)
+ mark = create_mark(material, {"kind": "question", "start_seconds": 18, "end_seconds": 18})
+ assert mark["start_seconds"] == mark["end_seconds"] == 18
+ with pytest.raises(service.TimedMediaError):
+ normalize_mark(material, {"kind": "question", "start_seconds": 5, "end_seconds": 1})
+
+
+async def test_suggestions_fall_back_without_llm_and_do_not_persist(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ store = service.TimedMediaStore(root=tmp_path / "timed_media")
+ material = _material(store)
+
+ async def unavailable(*_args: object, **_kwargs: object) -> str:
+ raise RuntimeError("llm unavailable")
+
+ monkeypatch.setattr("deeptutor.services.llm.complete", unavailable)
+ suggestions = await suggest_marks(material, 20)
+ assert suggestions
+ assert all("mark_id" not in row for row in suggestions)
+ assert store.get(material["material_id"])["learning"].get("marks", []) == []
+
+
+def test_heuristic_suggestions_use_current_segment(tmp_path: Path) -> None:
+ store = service.TimedMediaStore(root=tmp_path / "timed_media")
+ suggestions = heuristic_suggestions(_material(store), 20)
+ assert suggestions[0]["start_seconds"] == 10
+ assert any(row["kind"] == "question" for row in suggestions)
+
+
+def test_router_mark_crud_and_isolation(client_and_store) -> None:
+ client, store = client_and_store
+ material = _material(store)
+ other = _material(store)
+ other["material_id"] = service.material_id_for("89ThCi5qq-A")
+ store.save(other)
+ material_id = material["material_id"]
+
+ created = client.post(
+ f"/api/video-learning/materials/{material_id}/marks",
+ json={
+ "kind": "key_point",
+ "start_seconds": 10,
+ "end_seconds": 18,
+ "quote": "Gradient descent finds a local minimum.",
+ },
+ )
+ assert created.status_code == 201
+ mark_id = created.json()["mark_id"]
+
+ point = client.post(
+ f"/api/video-learning/materials/{material_id}/marks",
+ json={"kind": "question", "start_seconds": 18, "end_seconds": 18},
+ )
+ assert point.status_code == 201
+ assert point.json()["end_seconds"] == 18
+ listed = client.get(f"/api/video-learning/materials/{material_id}/marks")
+ assert listed.status_code == 200
+ assert [row["mark_id"] for row in listed.json()] == [mark_id, point.json()["mark_id"]]
+
+ patched = client.patch(
+ f"/api/video-learning/materials/{material_id}/marks/{mark_id}",
+ json={"note": "core claim"},
+ )
+ assert patched.status_code == 200
+ assert patched.json()["note"] == "core claim"
+
+ missing = client.patch(
+ f"/api/video-learning/materials/{other['material_id']}/marks/{mark_id}",
+ json={"note": "stolen"},
+ )
+ assert missing.status_code == 404
+
+ deleted = client.delete(f"/api/video-learning/materials/{material_id}/marks/{mark_id}")
+ assert deleted.status_code == 200
+ assert [row["mark_id"] for row in store.get(material_id)["learning"]["marks"]] == [
+ point.json()["mark_id"]
+ ]
+
+
+def test_router_suggestions_are_ephemeral(client_and_store, monkeypatch) -> None:
+ client, store = client_and_store
+ material = _material(store)
+
+ async def fake_complete(*_args: object, **_kwargs: object) -> str:
+ return '[{"kind":"review","start_seconds":40,"end_seconds":55,"quote":"invented quote"}]'
+
+ monkeypatch.setattr("deeptutor.services.llm.complete", fake_complete)
+ response = client.post(
+ f"/api/video-learning/materials/{material['material_id']}/mark-suggestions",
+ json={"time_seconds": 42},
+ )
+ assert response.status_code == 200
+ assert response.json()["suggestions"]
+ assert response.json()["suggestions"][0]["quote"] == "This example is worth reviewing later."
+ assert store.get(material["material_id"])["learning"].get("marks", []) == []
diff --git a/tests/video_learning/test_service.py b/tests/video_learning/test_service.py
index 51f216655..1993ee162 100644
--- a/tests/video_learning/test_service.py
+++ b/tests/video_learning/test_service.py
@@ -8,6 +8,7 @@ from types import SimpleNamespace
import pytest
from deeptutor.video_learning import service
+from deeptutor.video_learning.marks import create_mark
class _Paths:
@@ -153,7 +154,10 @@ def test_store_repairs_legacy_caption_entities(isolated: Path) -> None:
"segments": [
{"locator": 7, "start": 0, "end": 1, "text": "Learn&nbsp;&nbsp;&amp; apply"}
],
- "learning": {"last_position": 0},
+ "learning": {
+ "last_position": 0,
+ "marks": [{"locator": 7, "quote": "Learn&nbsp;&nbsp;&amp; apply"}],
+ },
}
)
@@ -162,6 +166,9 @@ def test_store_repairs_legacy_caption_entities(isolated: Path) -> None:
assert repaired["transcript"]["cues"][0]["text"] == "Learn & apply"
assert repaired["segments"] == [{"locator": 7, "start": 0, "end": 1, "text": "Learn & apply"}]
+ assert repaired["learning"]["marks"] == [
+ {"locator": 7, "quote": "Learn&nbsp;&nbsp;&amp; apply"}
+ ]
persisted = json.loads(store._path(material_id).read_text(encoding="utf-8"))
assert persisted["transcript"]["cues"][0]["text"] == "Learn & apply"
assert store.get(material_id)["segments"][0]["text"] == "Learn & apply"
@@ -303,6 +310,10 @@ async def test_provider_switch_preserves_material_and_progress(monkeypatch, isol
first = await service.resolve_material("https://youtu.be/dQw4w9WgXcQ")
stored = service.get_timed_media_store().get(first["material_id"])
stored["learning"]["last_position"] = 42
+ mark = create_mark(
+ stored,
+ {"kind": "key_point", "start_seconds": 1, "end_seconds": 12},
+ )
service.get_timed_media_store().save(stored)
service.save_video_learning_settings(
{
@@ -314,6 +325,7 @@ async def test_provider_switch_preserves_material_and_progress(monkeypatch, isol
second = await service.resolve_material("https://youtu.be/dQw4w9WgXcQ")
assert second["material_id"] == first["material_id"]
assert second["learning"]["last_position"] == 42
+ assert second["learning"]["marks"] == [mark]
assert second["playback"]["provider"] == "invidious"
@@ -385,7 +397,26 @@ async def test_refresh_invidious_transcript_preserves_playback_and_progress(
"metadata": {"title": "Retry lesson", "duration_seconds": 120},
"transcript": {"status": "unavailable", "reason": "unavailable", "cues": []},
"segments": [],
- "learning": {"last_position": 42},
+ "learning": {
+ "last_position": 42,
+ "marks": [
+ {
+ "mark_id": "0123456789abcdef01234567",
+ "kind": "review",
+ "start_seconds": 1,
+ "end_seconds": 4,
+ "start_locator": 0,
+ "end_locator": 0,
+ "quote": "",
+ "note": "",
+ "author": "user",
+ "source": "immersive",
+ "metadata": {},
+ "created_at": "2026-01-01T00:00:00Z",
+ "updated_at": "2026-01-01T00:00:00Z",
+ }
+ ],
+ },
"provider_cache": {
"invidious_formats": [{"format_id": "18", "mime_type": "video/mp4"}]
},
@@ -411,6 +442,7 @@ async def test_refresh_invidious_transcript_preserves_playback_and_progress(
{"locator": 1, "start": 1, "end": 4, "text": "Recovered caption."}
]
assert refreshed["learning"]["last_position"] == 42
+ assert len(refreshed["learning"]["marks"]) == 1
assert refreshed["playback"]["format_id"] == "18"
assert "revision=" in refreshed["playback"]["subtitles_url"]
diff --git a/web/components/watching/WatchingMarksPanel.tsx b/web/components/watching/WatchingMarksPanel.tsx
new file mode 100644
index 000000000..84fd39afb
--- /dev/null
+++ b/web/components/watching/WatchingMarksPanel.tsx
@@ -0,0 +1,216 @@
+"use client";
+
+import { useState } from "react";
+import { Bookmark, HelpCircle, Loader2, Play, RotateCcw, Trash2, X } from "lucide-react";
+import { useTranslation } from "react-i18next";
+
+import type {
+ VideoLearningMark,
+ VideoMarkKind,
+ VideoMarkSuggestion,
+} from "@/lib/video-learning-api";
+import {
+ VIDEO_MARK_COLORS,
+ filterMarks,
+ formatMarkRange,
+ markCoversTime,
+} from "@/lib/video-learning-marks";
+
+const FILTERS: Array<VideoMarkKind | "all"> = [
+ "all",
+ "key_point",
+ "question",
+ "review",
+];
+
+export function WatchingMarksPanel({
+ marks,
+ suggestions,
+ currentTime = 0,
+ error = null,
+ busy = false,
+ onSeek,
+ onDelete,
+ onReview,
+ onSaveSuggestion,
+ onDismissSuggestion,
+}: {
+ marks: VideoLearningMark[];
+ suggestions: VideoMarkSuggestion[];
+ currentTime?: number;
+ error?: string | null;
+ busy?: boolean;
+ onSeek(seconds: number): void;
+ onDelete(markId: string): void;
+ onReview(mark: VideoLearningMark): void;
+ onSaveSuggestion(suggestion: VideoMarkSuggestion): void;
+ onDismissSuggestion?(suggestion: VideoMarkSuggestion): void;
+}) {
+ const { t } = useTranslation();
+ const [filter, setFilter] = useState<VideoMarkKind | "all">("all");
+ const visible = filterMarks(marks, filter);
+
+ return (
+ <div className="space-y-3">
+ {error && (
+ <p
+ role="alert"
+ className="rounded-lg border border-[var(--border)] bg-[var(--muted)] px-3 py-2 text-sm text-[var(--destructive)]"
+ >
+ {error}
+ </p>
+ )}
+
+ {suggestions.length > 0 && (
+ <section className="space-y-2 rounded-lg border border-dashed border-[var(--border)] p-3">
+ <h4 className="text-xs font-semibold uppercase tracking-wide text-[var(--muted-foreground)]">
+ {t("Suggested marks")}
+ </h4>
+ {suggestions.map((suggestion, index) => (
+ <article
+ key={`${suggestion.kind}-${suggestion.start_seconds}-${index}`}
+ className="rounded-md bg-[var(--muted)]/50 p-2"
+ >
+ <div className="flex items-center gap-2">
+ <span
+ className="text-xs font-medium"
+ style={{ color: VIDEO_MARK_COLORS[suggestion.kind] }}
+ >
+ {markLabel(suggestion.kind, t)}
+ </span>
+ <button
+ type="button"
+ onClick={() => onSeek(suggestion.start_seconds)}
+ className="ml-auto font-mono text-xs text-blue-600"
+ >
+ {formatMarkRange(suggestion)}
+ </button>
+ <button
+ type="button"
+ onClick={() => onSaveSuggestion(suggestion)}
+ disabled={busy}
+ className="rounded-md bg-[var(--primary)] px-2 py-1 text-xs text-[var(--primary-foreground)] disabled:opacity-50"
+ >
+ {busy ? <Loader2 className="h-3 w-3 animate-spin" /> : t("Save")}
+ </button>
+ {onDismissSuggestion && (
+ <button
+ type="button"
+ onClick={() => onDismissSuggestion(suggestion)}
+ disabled={busy}
+ aria-label={t("Dismiss suggestion")}
+ className="rounded-md p-1 text-[var(--muted-foreground)] hover:bg-[var(--muted)] disabled:opacity-50"
+ >
+ <X className="h-3.5 w-3.5" />
+ </button>
+ )}
+ </div>
+ {suggestion.quote && (
+ <p className="mt-1 text-sm">{suggestion.quote}</p>
+ )}
+ </article>
+ ))}
+ </section>
+ )}
+
+ <div
+ className="flex flex-wrap gap-1"
+ role="group"
+ aria-label={t("Filter marks")}
+ >
+ {FILTERS.map((kind) => (
+ <button
+ key={kind}
+ type="button"
+ onClick={() => setFilter(kind)}
+ aria-pressed={filter === kind}
+ className={`rounded-full px-2.5 py-1 text-xs ${filter === kind ? "bg-[var(--muted)] font-semibold" : "text-[var(--muted-foreground)] hover:bg-[var(--muted)]/60"}`}
+ >
+ {kind === "all" ? t("All") : markLabel(kind, t)}
+ </button>
+ ))}
+ </div>
+
+ {visible.length ? (
+ <div className="space-y-2">
+ {visible.map((mark) => {
+ const active = markCoversTime(mark, currentTime);
+ return (
+ <article
+ key={mark.mark_id}
+ data-testid={`watching-mark-${mark.kind}`}
+ className={`rounded-lg border p-3 ${active ? "border-blue-500/40 bg-blue-500/10" : "border-[var(--border)]"}`}
+ >
+ <div className="flex items-center gap-2">
+ {mark.kind === "question" ? (
+ <HelpCircle className="h-4 w-4" />
+ ) : (
+ <Bookmark className="h-4 w-4" />
+ )}
+ <span
+ className="text-xs font-medium"
+ style={{ color: VIDEO_MARK_COLORS[mark.kind] }}
+ >
+ {markLabel(mark.kind, t)}
+ </span>
+ <button
+ type="button"
+ onClick={() => onSeek(mark.start_seconds)}
+ className="ml-auto inline-flex items-center gap-1 font-mono text-xs text-blue-600"
+ >
+ <Play className="h-3 w-3" />
+ {formatMarkRange(mark)}
+ </button>
+ {!mark.reviewed_at && mark.kind === "review" && (
+ <button
+ type="button"
+ onClick={() => onReview(mark)}
+ disabled={busy}
+ aria-label={t("Mark as reviewed")}
+ className="rounded-md p-1.5 hover:bg-[var(--muted)] disabled:opacity-50"
+ >
+ <RotateCcw className="h-3.5 w-3.5" />
+ </button>
+ )}
+ <button
+ type="button"
+ onClick={() => onDelete(mark.mark_id)}
+ disabled={busy}
+ aria-label={t("Delete mark")}
+ className="rounded-md p-1.5 text-[var(--destructive)] hover:bg-[var(--destructive)]/10 disabled:opacity-50"
+ >
+ <Trash2 className="h-3.5 w-3.5" />
+ </button>
+ </div>
+ {mark.quote && <p className="mt-2 text-sm">{mark.quote}</p>}
+ {mark.note && (
+ <p className="mt-1 text-xs text-[var(--muted-foreground)]">
+ {mark.note}
+ </p>
+ )}
+ {mark.reviewed_at && (
+ <p className="mt-1 text-xs text-[var(--muted-foreground)]">
+ {t("Reviewed")}
+ </p>
+ )}
+ </article>
+ );
+ })}
+ </div>
+ ) : (
+ <p className="text-sm text-[var(--muted-foreground)]">
+ {t("No marks yet.")}
+ </p>
+ )}
+ </div>
+ );
+}
+
+function markLabel(
+ kind: VideoMarkKind,
+ t: (key: string) => string,
+): string {
+ if (kind === "question") return t("Question");
+ if (kind === "review") return t("Review later");
+ return t("Key point");
+}
diff --git a/web/components/watching/WatchingPane.tsx b/web/components/watching/WatchingPane.tsx
index e6dadd2cf..91dd2f56a 100644
--- a/web/components/watching/WatchingPane.tsx
+++ b/web/components/watching/WatchingPane.tsx
@@ -3,6 +3,8 @@
import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
import {
AlertTriangle,
+ Bookmark,
+ BookmarkPlus,
ChevronDown,
ChevronUp,
ChevronsDown,
@@ -15,6 +17,7 @@ import {
Play,
RotateCcw,
Search,
+ Sparkles,
StickyNote,
Trash2,
X,
@@ -29,22 +32,35 @@ import {
type PlayerController,
} from '@/lib/video-player-controller'
import {
+ createVideoMark,
createVideoNote,
+ deleteVideoMark,
deleteVideoNote,
exportVideoNotes,
+ listVideoMarks,
listVideoNotes,
saveVideoProgress,
+ suggestVideoMarks,
+ updateVideoMark,
updateVideoNote,
+ type SuggestedVideoMark,
+ type VideoMark,
+ type VideoMarkKind,
type VideoNote,
} from '@/lib/video-learning-api'
+import {
+ cueIndexesFromSelection,
+ cuesToRange,
+} from '@/lib/video-learning-marks'
import { stepTranscriptMatch, transcriptMatchIndexes } from '@/lib/transcript-search'
import { videoTimeFromHref } from '@/lib/watching-citations'
+import { WatchingMarksPanel } from './WatchingMarksPanel'
import { WatchingPlayer } from './WatchingPlayer'
import { transcriptFollowScrollTop } from '@/lib/transcript-follow'
export const WATCHING_ASK_EVENT = 'dt:watching-ask'
-type WatchTab = 'transcript' | 'notes'
+type WatchTab = 'transcript' | 'notes' | 'marks'
export function WatchingPane({ onClose }: { onClose(): void }) {
const { t } = useTranslation()
@@ -96,6 +112,21 @@ export function WatchingPane({ onClose }: { onClose(): void }) {
const stateRef = useRef({ time: 0, duration: 0 })
activeMaterialIdRef.current = materialId
+ const [marks, setMarks] = useState<VideoMark[]>([])
+ const [marksLoading, setMarksLoading] = useState(false)
+ const [marksError, setMarksError] = useState<string | null>(null)
+ const [markDraft, setMarkDraft] = useState<{
+ kind: VideoMarkKind
+ start_seconds: number
+ end_seconds: number | null
+ quote?: string
+ note: string
+ } | null>(null)
+ const [suggestedMarks, setSuggestedMarks] = useState<SuggestedVideoMark[]>([])
+ const [suggestionsLoading, setSuggestionsLoading] = useState(false)
+ const [markBusy, setMarkBusy] = useState(false)
+ const marksLoadRequestRef = useRef(0)
+
useEffect(() => {
setActive(true)
return () => setActive(false)
@@ -184,7 +215,7 @@ export function WatchingPane({ onClose }: { onClose(): void }) {
useEffect(() => {
if (!followTranscript || tab !== 'transcript' || !cue) return
const list = transcriptListRef.current
- const activeRow = list?.querySelector<HTMLButtonElement>('[data-active-cue="true"]')
+ const activeRow = list?.querySelector<HTMLElement>('[data-active-cue="true"]')
if (!list || !activeRow) return
const targetTop = transcriptFollowScrollTop({
rowOffset:
@@ -261,6 +292,41 @@ export function WatchingPane({ onClose }: { onClose(): void }) {
}
}, [materialId, t])
+ useEffect(() => {
+ let cancelled = false
+ setMarks([])
+ setMarksError(null)
+ setMarkDraft(null)
+ setSuggestedMarks([])
+ const requestId = ++marksLoadRequestRef.current
+ if (!materialId) {
+ setMarksLoading(false)
+ return () => {
+ cancelled = true
+ }
+ }
+ setMarksLoading(true)
+ void (async () => {
+ try {
+ const loaded = await listVideoMarks(materialId)
+ if (!cancelled && marksLoadRequestRef.current === requestId) {
+ setMarks(loaded)
+ }
+ } catch {
+ if (!cancelled && marksLoadRequestRef.current === requestId) {
+ setMarksError(t('Marks could not be loaded.'))
+ }
+ } finally {
+ if (!cancelled && marksLoadRequestRef.current === requestId) {
+ setMarksLoading(false)
+ }
+ }
+ })()
+ return () => {
+ cancelled = true
+ }
+ }, [materialId, t])
+
const sortNotes = (rows: VideoNote[]) =>
[...rows].sort(
(left, right) =>
@@ -421,6 +487,240 @@ export function WatchingPane({ onClose }: { onClose(): void }) {
},
[material, selectedTranscriptMatch, transcriptMatches]
)
+
+ const handleMarkHere = () => {
+ setMarkDraft({
+ kind: 'key_point',
+ start_seconds: time,
+ end_seconds: null,
+ note: '',
+ })
+ }
+
+ const handleMarkSelection = () => {
+ if (!material?.transcript.cues.length) {
+ handleMarkHere()
+ return
+ }
+ const selected = cueIndexesFromSelection(
+ transcriptListRef.current,
+ window.getSelection()
+ )
+ if (selected.length === 0) {
+ handleMarkHere()
+ return
+ }
+ const range = cuesToRange(material.transcript.cues, selected)
+ if (!range) {
+ handleMarkHere()
+ return
+ }
+ setMarkDraft({
+ kind: 'key_point',
+ start_seconds: range.start_seconds,
+ end_seconds: range.end_seconds,
+ quote: range.quote,
+ note: '',
+ })
+ }
+
+ const handleMarkCue = (index: number) => {
+ const cueItem = material?.transcript.cues[index]
+ if (!cueItem) return
+ setMarkDraft({
+ kind: 'key_point',
+ start_seconds: cueItem.start,
+ end_seconds: cueItem.end,
+ quote: cueItem.text,
+ note: '',
+ })
+ }
+
+ const handleSaveMarkDraft = async () => {
+ if (!materialId || !markDraft) return
+ const requestedMaterialId = materialId
+ setMarkBusy(true)
+ try {
+ const saved = await createVideoMark(requestedMaterialId, {
+ kind: markDraft.kind,
+ start_seconds: markDraft.start_seconds,
+ end_seconds: markDraft.end_seconds ?? markDraft.start_seconds,
+ quote: markDraft.quote,
+ note: markDraft.note.trim() || undefined,
+ })
+ if (activeMaterialIdRef.current !== requestedMaterialId) return
+ setMarks(prev =>
+ [...prev, saved].sort((a, b) => a.start_seconds - b.start_seconds)
+ )
+ setMarkDraft(null)
+ } catch {
+ if (activeMaterialIdRef.current === requestedMaterialId) {
+ setMarksError(t('Mark was not saved.'))
+ }
+ } finally {
+ setMarkBusy(false)
+ }
+ }
+
+ const handleDeleteMark = async (markId: string) => {
+ if (!materialId) return
+ const requestedMaterialId = materialId
+ setMarkBusy(true)
+ try {
+ await deleteVideoMark(requestedMaterialId, markId)
+ if (activeMaterialIdRef.current !== requestedMaterialId) return
+ setMarks(prev => prev.filter(m => m.mark_id !== markId))
+ } catch {
+ if (activeMaterialIdRef.current === requestedMaterialId) {
+ setMarksError(t('Mark was not deleted.'))
+ }
+ } finally {
+ setMarkBusy(false)
+ }
+ }
+
+ const handleReviewMark = async (mark: VideoMark) => {
+ if (!materialId) return
+ const requestedMaterialId = materialId
+ setMarkBusy(true)
+ try {
+ const updated = await updateVideoMark(requestedMaterialId, mark.mark_id, {
+ reviewed: true,
+ })
+ if (activeMaterialIdRef.current !== requestedMaterialId) return
+ setMarks(prev =>
+ prev.map(m => (m.mark_id === mark.mark_id ? updated : m))
+ )
+ } catch {
+ if (activeMaterialIdRef.current === requestedMaterialId) {
+ setMarksError(t('Mark was not updated.'))
+ }
+ } finally {
+ setMarkBusy(false)
+ }
+ }
+
+ const handleRequestSuggestions = async () => {
+ if (!materialId) return
+ const requestedMaterialId = materialId
+ setSuggestionsLoading(true)
+ setMarksError(null)
+ try {
+ const res = await suggestVideoMarks(requestedMaterialId, time)
+ if (activeMaterialIdRef.current !== requestedMaterialId) return
+ setSuggestedMarks(res)
+ setTab('marks')
+ } catch {
+ if (activeMaterialIdRef.current === requestedMaterialId) {
+ setMarksError(t('Suggestions could not be loaded.'))
+ }
+ } finally {
+ setSuggestionsLoading(false)
+ }
+ }
+
+ const handleConfirmSuggestion = async (suggestion: SuggestedVideoMark) => {
+ if (!materialId) return
+ const requestedMaterialId = materialId
+ setMarkBusy(true)
+ try {
+ const saved = await createVideoMark(requestedMaterialId, {
+ kind: suggestion.kind,
+ start_seconds: suggestion.start_seconds,
+ end_seconds: suggestion.end_seconds,
+ start_locator: suggestion.start_locator,
+ end_locator: suggestion.end_locator,
+ quote: suggestion.quote,
+ note: suggestion.note,
+ })
+ if (activeMaterialIdRef.current !== requestedMaterialId) return
+ setMarks(prev =>
+ [...prev, saved].sort((a, b) => a.start_seconds - b.start_seconds)
+ )
+ setSuggestedMarks(prev => prev.filter(s => s !== suggestion))
+ } catch {
+ if (activeMaterialIdRef.current === requestedMaterialId) {
+ setMarksError(t('Mark was not saved.'))
+ }
+ } finally {
+ setMarkBusy(false)
+ }
+ }
+
+ const handleDismissSuggestion = (suggestion: SuggestedVideoMark) => {
+ setSuggestedMarks(prev => prev.filter(s => s !== suggestion))
+ }
+
+ const markDraftCard = markDraft && (
+ <div className="rounded-lg border border-blue-500/30 bg-blue-500/5 p-3 text-sm">
+ <div className="flex items-center justify-between gap-2">
+ <span className="font-mono text-xs font-semibold text-blue-600">
+ {formatTime(markDraft.start_seconds)}
+ {markDraft.end_seconds != null
+ ? ` - ${formatTime(markDraft.end_seconds)}`
+ : ''}
+ </span>
+ <div className="flex gap-1">
+ {(['key_point', 'question', 'review'] as const).map(k => (
+ <button
+ key={k}
+ type="button"
+ onClick={() =>
+ setMarkDraft(prev => (prev ? { ...prev, kind: k } : null))
+ }
+ className={`rounded px-2 py-0.5 text-xs font-medium ${
+ markDraft.kind === k
+ ? 'bg-blue-600 text-white'
+ : 'bg-[var(--muted)] text-[var(--muted-foreground)]'
+ }`}
+ >
+ {k === 'key_point'
+ ? t('Key point')
+ : k === 'question'
+ ? t('Question')
+ : t('Review later')}
+ </button>
+ ))}
+ </div>
+ </div>
+ {markDraft.quote && (
+ <p className="mt-2 border-l-2 border-blue-500/40 pl-2 text-xs italic text-[var(--muted-foreground)]">
+ {markDraft.quote}
+ </p>
+ )}
+ <input
+ type="text"
+ value={markDraft.note}
+ onChange={e => {
+ const val = e.target.value
+ setMarkDraft(prev => (prev ? { ...prev, note: val } : null))
+ }}
+ placeholder={t('Draft note or reason...')}
+ className="mt-2 w-full rounded border border-[var(--border)] bg-transparent px-2 py-1 text-xs"
+ />
+ <div className="mt-2 flex justify-end gap-2">
+ <button
+ type="button"
+ onClick={() => setMarkDraft(null)}
+ className="rounded px-2 py-1 text-xs text-[var(--muted-foreground)] hover:bg-[var(--muted)]"
+ >
+ {t('Cancel')}
+ </button>
+ <button
+ type="button"
+ onClick={() => void handleSaveMarkDraft()}
+ disabled={markBusy}
+ className="rounded bg-blue-600 px-2 py-1 text-xs font-medium text-white hover:bg-blue-700 disabled:opacity-50"
+ >
+ {markBusy ? (
+ <Loader2 className="mr-1 inline h-3 w-3 animate-spin" />
+ ) : null}
+ {t('Save mark')}
+ </button>
+ </div>
+ </div>
+ )
+
return (
<section className="flex h-full min-w-0 flex-col border-r border-[var(--border)] bg-[var(--background)]">
<header className="flex items-center gap-2 border-b border-[var(--border)] px-4 py-3">
@@ -605,11 +905,11 @@ export function WatchingPane({ onClose }: { onClose(): void }) {
}}
>
<div
- className="mb-3 grid w-full max-w-56 grid-cols-2 rounded-lg bg-[var(--muted)] p-1"
+ className="mb-3 grid w-full max-w-xs grid-cols-3 rounded-lg bg-[var(--muted)] p-1"
role="tablist"
aria-label={t('Video learning panels')}
>
- {(['transcript', 'notes'] as const).map(item => (
+ {(['transcript', 'marks', 'notes'] as const).map(item => (
<button
key={item}
type="button"
@@ -626,6 +926,11 @@ export function WatchingPane({ onClose }: { onClose(): void }) {
<Captions className="h-3.5 w-3.5" />
{t('Transcript')}
</>
+ ) : item === 'marks' ? (
+ <>
+ <Bookmark className="h-3.5 w-3.5" />
+ {t('Marks')}
+ </>
) : (
<>
<StickyNote className="h-3.5 w-3.5" />
@@ -730,6 +1035,37 @@ export function WatchingPane({ onClose }: { onClose(): void }) {
>
{t('Explain here')}
</button>
+ <button
+ type="button"
+ onClick={handleMarkHere}
+ disabled={!material}
+ className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--border)] px-3 py-2 text-sm font-medium hover:bg-[var(--muted)] disabled:opacity-50"
+ >
+ <Bookmark className="h-4 w-4" />
+ {t('Mark here')}
+ </button>
+ <button
+ type="button"
+ onClick={handleMarkSelection}
+ disabled={!material?.transcript.cues.length}
+ className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--border)] px-3 py-2 text-sm font-medium hover:bg-[var(--muted)] disabled:opacity-50"
+ >
+ <BookmarkPlus className="h-4 w-4" />
+ {t('Use selection')}
+ </button>
+ <button
+ type="button"
+ onClick={() => void handleRequestSuggestions()}
+ disabled={suggestionsLoading || !material?.transcript.cues.length}
+ className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--border)] px-3 py-2 text-sm font-medium hover:bg-[var(--muted)] disabled:opacity-50"
+ >
+ {suggestionsLoading ? (
+ <Loader2 className="h-4 w-4 animate-spin" />
+ ) : (
+ <Sparkles className="h-4 w-4" />
+ )}
+ {t('Suggest marks')}
+ </button>
<button
type="button"
onClick={() => setFollowTranscript(current => !current)}
@@ -741,6 +1077,7 @@ export function WatchingPane({ onClose }: { onClose(): void }) {
{t('Follow playback')}
</button>
</div>
+ {markDraftCard}
{normalizedTranscriptQuery && transcriptMatches.length === 0 ? (
<p className="rounded-lg border border-[var(--border)] p-4 text-sm text-[var(--muted-foreground)]">
{t('No transcript matches.')}
@@ -761,31 +1098,84 @@ export function WatchingPane({ onClose }: { onClose(): void }) {
Boolean(normalizedTranscriptQuery) &&
transcriptMatches[selectedTranscriptMatch] === index
return (
- <button
+ <div
key={`${row.start}-${index}`}
- type="button"
data-active-cue={active ? 'true' : undefined}
data-transcript-cue={index}
- onClick={() => controllerRef.current?.seek(row.start)}
- className={`flex w-full gap-3 rounded-md px-2 py-1.5 text-left text-sm ${
- active
- ? 'bg-blue-500/15 ring-1 ring-blue-500/30'
- : selectedMatch
- ? 'bg-violet-500/10 ring-1 ring-violet-500/30'
- : 'hover:bg-[var(--muted)]'
- }`}
+ data-cue-index={index}
+ className="group flex w-full items-start justify-between gap-2 rounded-md px-2 py-1.5 text-left text-sm hover:bg-[var(--muted)]"
>
- <span className="shrink-0 tabular-nums text-blue-600">
- {formatTime(row.start)}
- </span>
- <span>{row.text}</span>
- </button>
+ <button
+ type="button"
+ onClick={() => controllerRef.current?.seek(row.start)}
+ className={`flex flex-1 items-start gap-3 rounded-md text-left ${
+ active
+ ? 'bg-blue-500/15 ring-1 ring-blue-500/30'
+ : selectedMatch
+ ? 'bg-violet-500/10 ring-1 ring-violet-500/30'
+ : ''
+ }`}
+ >
+ <span className="shrink-0 tabular-nums text-blue-600">
+ {formatTime(row.start)}
+ </span>
+ <span>{row.text}</span>
+ </button>
+ <button
+ type="button"
+ onClick={() => handleMarkCue(index)}
+ aria-label={t('Mark this subtitle')}
+ className="shrink-0 rounded p-1 text-[var(--muted-foreground)] opacity-0 hover:bg-[var(--muted)] hover:text-[var(--foreground)] group-hover:opacity-100 focus:opacity-100"
+ >
+ <BookmarkPlus className="h-3.5 w-3.5" />
+ </button>
+ </div>
)
})}
</div>
)}
</>
)
+ ) : tab === 'marks' ? (
+ <div className="space-y-3">
+ <div className="flex flex-wrap items-center gap-2">
+ <button
+ type="button"
+ onClick={handleMarkHere}
+ disabled={!material}
+ className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--border)] px-3 py-2 text-sm font-medium hover:bg-[var(--muted)] disabled:opacity-50"
+ >
+ <Bookmark className="h-4 w-4" />
+ {t('Mark here')}
+ </button>
+ <button
+ type="button"
+ onClick={() => void handleRequestSuggestions()}
+ disabled={suggestionsLoading || !material?.transcript.cues.length}
+ className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--border)] px-3 py-2 text-sm font-medium hover:bg-[var(--muted)] disabled:opacity-50"
+ >
+ {suggestionsLoading ? (
+ <Loader2 className="h-4 w-4 animate-spin" />
+ ) : (
+ <Sparkles className="h-4 w-4" />
+ )}
+ {t('Suggest marks')}
+ </button>
+ </div>
+ {markDraftCard}
+ <WatchingMarksPanel
+ marks={marks}
+ suggestions={suggestedMarks}
+ currentTime={time}
+ busy={markBusy || marksLoading}
+ error={marksError}
+ onSeek={seekTime => controllerRef.current?.seek(seekTime)}
+ onDelete={id => void handleDeleteMark(id)}
+ onReview={m => void handleReviewMark(m)}
+ onSaveSuggestion={s => void handleConfirmSuggestion(s)}
+ onDismissSuggestion={handleDismissSuggestion}
+ />
+ </div>
) : (
<div className="space-y-3">
<form
diff --git a/web/lib/video-learning-api.ts b/web/lib/video-learning-api.ts
index 6704c3385..8cbf89d51 100644
--- a/web/lib/video-learning-api.ts
+++ b/web/lib/video-learning-api.ts
@@ -8,6 +8,9 @@ export interface TranscriptCue {
text: string;
}
+export type VideoMark = VideoLearningMark;
+export type SuggestedVideoMark = VideoMarkSuggestion;
+
export interface TimedSegment extends TranscriptCue {
locator: number;
}
@@ -53,10 +56,42 @@ export interface TimedMediaMaterial {
cues: TranscriptCue[];
};
segments: TimedSegment[];
- learning: { last_position: number };
+ learning: { last_position: number; marks?: VideoLearningMark[] };
playback: VideoPlayback;
}
+export type VideoMarkKind = "key_point" | "question" | "review";
+export type VideoMarkAuthor = "user" | "assistant";
+export type VideoMarkSource = "immersive";
+
+export interface VideoLearningMark {
+ mark_id: string;
+ kind: VideoMarkKind;
+ start_seconds: number;
+ end_seconds: number;
+ start_locator: number;
+ end_locator: number;
+ quote: string;
+ note: string;
+ author: VideoMarkAuthor;
+ source?: VideoMarkSource;
+ metadata?: Record<string, unknown>;
+ created_at: string;
+ updated_at: string;
+ reviewed_at?: string;
+}
+
+export interface VideoMarkSuggestion {
+ kind: VideoMarkKind;
+ start_seconds: number;
+ end_seconds: number;
+ start_locator: number;
+ end_locator: number;
+ quote: string;
+ note: string;
+ author: VideoMarkAuthor;
+}
+
export interface VideoNote {
notebook_id: string;
note_id: string;
@@ -243,6 +278,95 @@ export async function saveVideoProgress(
);
}
+export async function listVideoMarks(
+ materialId: string,
+): Promise<VideoLearningMark[]> {
+ return unwrap(
+ await apiFetch(
+ apiUrl(
+ `/api/video-learning/materials/${encodeURIComponent(materialId)}/marks`,
+ ),
+ { cache: "no-store" },
+ ),
+ );
+}
+
+export async function createVideoMark(
+ materialId: string,
+ payload: {
+ kind: VideoMarkKind;
+ start_seconds: number;
+ end_seconds?: number | null;
+ start_locator?: number;
+ end_locator?: number;
+ quote?: string;
+ note?: string;
+ },
+): Promise<VideoLearningMark> {
+ return unwrap(
+ await apiFetch(
+ apiUrl(`/api/video-learning/materials/${encodeURIComponent(materialId)}/marks`),
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(payload),
+ },
+ ),
+ );
+}
+
+export async function updateVideoMark(
+ materialId: string,
+ markId: string,
+ payload: Partial<{ reviewed: boolean; note: string }>,
+): Promise<VideoLearningMark> {
+ return unwrap(
+ await apiFetch(
+ apiUrl(
+ `/api/video-learning/materials/${encodeURIComponent(materialId)}/marks/${encodeURIComponent(markId)}`,
+ ),
+ {
+ method: "PATCH",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(payload),
+ },
+ ),
+ );
+}
+
+export async function deleteVideoMark(
+ materialId: string,
+ markId: string,
+): Promise<void> {
+ await unwrap(
+ await apiFetch(
+ apiUrl(
+ `/api/video-learning/materials/${encodeURIComponent(materialId)}/marks/${encodeURIComponent(markId)}`,
+ ),
+ { method: "DELETE" },
+ ),
+ );
+}
+
+export async function suggestVideoMarks(
+ materialId: string,
+ timeSeconds = 0,
+): Promise<VideoMarkSuggestion[]> {
+ const payload = await unwrap<{ suggestions: VideoMarkSuggestion[] }>(
+ await apiFetch(
+ apiUrl(
+ `/api/video-learning/materials/${encodeURIComponent(materialId)}/mark-suggestions`,
+ ),
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ time_seconds: timeSeconds }),
+ },
+ ),
+ );
+ return payload.suggestions || [];
+}
+
export async function getVideoLearningSettings(): Promise<VideoLearningSettings> {
return unwrap(
await apiFetch(apiUrl("/api/settings/video-learning"), {
diff --git a/web/lib/video-learning-marks.ts b/web/lib/video-learning-marks.ts
new file mode 100644
index 000000000..18b963ce2
--- /dev/null
+++ b/web/lib/video-learning-marks.ts
@@ -0,0 +1,138 @@
+import type {
+ TimedSegment,
+ TranscriptCue,
+ VideoLearningMark,
+ VideoMarkKind,
+} from "./video-learning-api";
+
+export const VIDEO_MARK_KINDS = ["key_point", "question", "review"] as const;
+
+export const VIDEO_MARK_COLORS: Record<VideoMarkKind, string> = {
+ key_point: "#b45309",
+ question: "#1d4ed8",
+ review: "#be123c",
+};
+
+export function uniqueSortedIndexes(values: number[]): number[] {
+ return [...new Set(values.filter((value) => Number.isInteger(value) && value >= 0))].sort(
+ (left, right) => left - right,
+ );
+}
+
+export function rangeFromCues(
+ cues: TranscriptCue[],
+ indexes: number[],
+): { start_seconds: number; end_seconds: number; quote: string } | null {
+ const selected = uniqueSortedIndexes(indexes)
+ .map((index) => cues[index])
+ .filter((cue): cue is TranscriptCue => Boolean(cue));
+ if (!selected.length) return null;
+ return {
+ start_seconds: Math.min(...selected.map((cue) => cue.start)),
+ end_seconds: Math.max(...selected.map((cue) => cue.end)),
+ quote: selected
+ .map((cue) => cue.text.trim())
+ .filter(Boolean)
+ .join(" "),
+ };
+}
+
+export function locatorsForRange(
+ segments: TimedSegment[],
+ start: number,
+ end: number,
+): { start_locator: number; end_locator: number } {
+ const overlapping = segments.filter(
+ (segment) => segment.end >= start && segment.start <= end,
+ );
+ if (!overlapping.length) return { start_locator: 0, end_locator: 0 };
+ return {
+ start_locator: overlapping[0].locator,
+ end_locator: overlapping[overlapping.length - 1].locator,
+ };
+}
+
+export function markCoversTime(
+ mark: Pick<VideoLearningMark, "start_seconds" | "end_seconds">,
+ time: number,
+): boolean {
+ if (mark.end_seconds <= mark.start_seconds) {
+ return Math.abs(time - mark.start_seconds) <= 1;
+ }
+ return time >= mark.start_seconds && time <= mark.end_seconds;
+}
+
+export function filterMarks(
+ marks: VideoLearningMark[],
+ kind: VideoMarkKind | "all",
+): VideoLearningMark[] {
+ const sorted = [...marks].sort(
+ (left, right) =>
+ left.start_seconds - right.start_seconds ||
+ left.end_seconds - right.end_seconds ||
+ left.mark_id.localeCompare(right.mark_id),
+ );
+ return kind === "all" ? sorted : sorted.filter((mark) => mark.kind === kind);
+}
+
+export function cueIndexesFromSelection(
+ root: ParentNode | null,
+ selection: Selection | null,
+): number[] {
+ if (!root || !selection || selection.rangeCount === 0 || selection.isCollapsed) {
+ return [];
+ }
+ const indexes: number[] = [];
+ for (let rangeIndex = 0; rangeIndex < selection.rangeCount; rangeIndex += 1) {
+ const range = selection.getRangeAt(rangeIndex);
+ const ancestor = range.commonAncestorContainer;
+ const ancestorElement =
+ ancestor instanceof Element ? ancestor : ancestor.parentElement;
+ if (!ancestorElement || !root.contains(ancestorElement)) continue;
+ const nodes = ancestorElement.querySelectorAll("[data-cue-index]");
+ const candidates = [ancestorElement, ...Array.from(nodes)];
+ for (const node of candidates) {
+ if (
+ !(node instanceof HTMLElement) ||
+ !node.hasAttribute("data-cue-index") ||
+ !range.intersectsNode(node)
+ ) {
+ continue;
+ }
+ const index = Number(node.getAttribute("data-cue-index"));
+ if (Number.isInteger(index)) indexes.push(index);
+ }
+ }
+ return uniqueSortedIndexes(indexes);
+}
+
+export function formatMarkRange(
+ mark: Pick<VideoLearningMark, "start_seconds" | "end_seconds">,
+): string {
+ if (mark.end_seconds <= mark.start_seconds) {
+ return formatMarkTime(mark.start_seconds);
+ }
+ return `${formatMarkTime(mark.start_seconds)} - ${formatMarkTime(mark.end_seconds)}`;
+}
+
+export function formatMarkTime(value: number): string {
+ const total = Math.max(0, Math.floor(value));
+ const hours = Math.floor(total / 3600);
+ const minutes = Math.floor((total % 3600) / 60);
+ const seconds = total % 60;
+ return hours
+ ? `${hours}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`
+ : `${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+}
+
+export const cuesToRange = rangeFromCues;
+
+export function cuesToSegmentLocators(
+ indexes: number[],
+ cues: TranscriptCue[],
+): { start_locator: number; end_locator: number } {
+ const range = rangeFromCues(cues, indexes);
+ if (!range) return { start_locator: 0, end_locator: 0 };
+ const segments = cues.map((cue, index) => ({ ...cue, locator: index + 1 }));
+ return locatorsForRange(segments, range.start_seconds, range.end_seconds);
+}
diff --git a/web/locales/de/app.json b/web/locales/de/app.json
index 80071a718..31c742eb8 100644
--- a/web/locales/de/app.json
+++ b/web/locales/de/app.json
@@ -5270,5 +5270,26 @@
"Move this knowledge base with its documents, settings, and indexes. Existing workspace assignments are updated.": "Diese Knowledge Base samt Dokumenten, Einstellungen und Indizes verschieben. Bestehende Workspace-Zuweisungen werden aktualisiert.",
"Review move": "Verschiebung prüfen",
"{{count}} files · {{bytes}} bytes": "{{count}} Dateien · {{bytes}} Bytes",
- "Assignments updated: {{names}}": "Aktualisierte Zuweisungen: {{names}}"
+ "Assignments updated: {{names}}": "Aktualisierte Zuweisungen: {{names}}",
+ "Marks": "Markierungen",
+ "Mark here": "Hier markieren",
+ "Use selection": "Auswahl verwenden",
+ "Mark this subtitle": "Diesen Untertitel markieren",
+ "Suggest marks": "Markierungen vorschlagen",
+ "Suggested marks": "Vorgeschlagene Markierungen",
+ "Delete mark": "Markierung löschen",
+ "Filter marks": "Markierungen filtern",
+ "Key point": "Kernpunkt",
+ "Review later": "Später wiederholen",
+ "Reviewed": "Wiederholt",
+ "Mark as reviewed": "Als wiederholt markieren",
+ "No marks yet.": "Noch keine Markierungen.",
+ "Dismiss suggestion": "Vorschlag verwerfen",
+ "Marks could not be loaded.": "Markierungen konnten nicht geladen werden.",
+ "Suggestions could not be loaded.": "Vorschläge konnten nicht geladen werden.",
+ "Mark was not saved.": "Markierung wurde nicht gespeichert.",
+ "Mark was not deleted.": "Markierung wurde nicht gelöscht.",
+ "Mark was not updated.": "Markierung wurde nicht aktualisiert.",
+ "Draft note or reason...": "Notiz oder Grund verfassen...",
+ "Save mark": "Markierung speichern"
}
diff --git a/web/locales/en/app.json b/web/locales/en/app.json
index c6167eb21..8dc010400 100644
--- a/web/locales/en/app.json
+++ b/web/locales/en/app.json
@@ -5270,5 +5270,26 @@
"Move this knowledge base with its documents, settings, and indexes. Existing workspace assignments are updated.": "Move this knowledge base with its documents, settings, and indexes. Existing workspace assignments are updated.",
"Review move": "Review move",
"{{count}} files · {{bytes}} bytes": "{{count}} files · {{bytes}} bytes",
- "Assignments updated: {{names}}": "Assignments updated: {{names}}"
+ "Assignments updated: {{names}}": "Assignments updated: {{names}}",
+ "Marks": "Marks",
+ "Mark here": "Mark here",
+ "Use selection": "Use selection",
+ "Mark this subtitle": "Mark this subtitle",
+ "Suggest marks": "Suggest marks",
+ "Suggested marks": "Suggested marks",
+ "Delete mark": "Delete mark",
+ "Filter marks": "Filter marks",
+ "Key point": "Key point",
+ "Review later": "Review later",
+ "Reviewed": "Reviewed",
+ "Mark as reviewed": "Mark as reviewed",
+ "No marks yet.": "No marks yet.",
+ "Dismiss suggestion": "Dismiss suggestion",
+ "Marks could not be loaded.": "Marks could not be loaded.",
+ "Suggestions could not be loaded.": "Suggestions could not be loaded.",
+ "Mark was not saved.": "Mark was not saved.",
+ "Mark was not deleted.": "Mark was not deleted.",
+ "Mark was not updated.": "Mark was not updated.",
+ "Draft note or reason...": "Draft note or reason...",
+ "Save mark": "Save mark"
}
diff --git a/web/locales/fr/app.json b/web/locales/fr/app.json
index 996e47743..ad0210c7b 100644
--- a/web/locales/fr/app.json
+++ b/web/locales/fr/app.json
@@ -5713,5 +5713,26 @@
"Move this knowledge base with its documents, settings, and indexes. Existing workspace assignments are updated.": "Déplacer cette base avec ses documents, paramètres et index. Les attributions existantes seront mises à jour.",
"Review move": "Vérifier le déplacement",
"{{count}} files · {{bytes}} bytes": "{{count}} fichiers · {{bytes}} octets",
- "Assignments updated: {{names}}": "Attributions mises à jour : {{names}}"
+ "Assignments updated: {{names}}": "Attributions mises à jour : {{names}}",
+ "Marks": "Marques",
+ "Mark here": "Marquer ici",
+ "Use selection": "Utiliser la sélection",
+ "Mark this subtitle": "Marquer ce sous-titre",
+ "Suggest marks": "Suggérer des marques",
+ "Suggested marks": "Marques suggérées",
+ "Delete mark": "Supprimer la marque",
+ "Filter marks": "Filtrer les marques",
+ "Key point": "Point clé",
+ "Review later": "À réviser plus tard",
+ "Reviewed": "Révisé",
+ "Mark as reviewed": "Marquer comme révisé",
+ "No marks yet.": "Aucune marque pour l'instant.",
+ "Dismiss suggestion": "Ignorer la suggestion",
+ "Marks could not be loaded.": "Impossible de charger les marques.",
+ "Suggestions could not be loaded.": "Impossible de charger les suggestions.",
+ "Mark was not saved.": "La marque n'a pas été enregistrée.",
+ "Mark was not deleted.": "La marque n'a pas été supprimée.",
+ "Mark was not updated.": "La marque n'a pas été mise à jour.",
+ "Draft note or reason...": "Rédiger une note ou un motif...",
+ "Save mark": "Enregistrer la marque"
}
diff --git a/web/locales/uk/app.json b/web/locales/uk/app.json
index 36788d166..479a51971 100644
--- a/web/locales/uk/app.json
+++ b/web/locales/uk/app.json
@@ -5286,5 +5286,26 @@
"Move this knowledge base with its documents, settings, and indexes. Existing workspace assignments are updated.": "Перемістити базу знань разом із документами, налаштуваннями та індексами. Наявні призначення робочих областей буде оновлено.",
"Review move": "Перевірити переміщення",
"{{count}} files · {{bytes}} bytes": "{{count}} файлів · {{bytes}} байтів",
- "Assignments updated: {{names}}": "Оновлені призначення: {{names}}"
+ "Assignments updated: {{names}}": "Оновлені призначення: {{names}}",
+ "Marks": "Позначки",
+ "Mark here": "Позначити тут",
+ "Use selection": "Використати виділення",
+ "Mark this subtitle": "Позначити цей субтитр",
+ "Suggest marks": "Запропонувати позначки",
+ "Suggested marks": "Запропоновані позначки",
+ "Delete mark": "Видалити позначку",
+ "Filter marks": "Фільтрувати позначки",
+ "Key point": "Ключовий пункт",
+ "Review later": "Повторити пізніше",
+ "Reviewed": "Повторено",
+ "Mark as reviewed": "Позначити як повторене",
+ "No marks yet.": "Поки немає позначок.",
+ "Dismiss suggestion": "Відхилити пропозицію",
+ "Marks could not be loaded.": "Не вдалося завантажити позначки.",
+ "Suggestions could not be loaded.": "Не вдалося завантажити пропозиції.",
+ "Mark was not saved.": "Позначку не збережено.",
+ "Mark was not deleted.": "Позначку не видалено.",
+ "Mark was not updated.": "Позначку не оновлено.",
+ "Draft note or reason...": "Чернетка примітки або причина...",
+ "Save mark": "Зберегти позначку"
}
diff --git a/web/locales/zh/app.json b/web/locales/zh/app.json
index 4312257b3..67ab0a642 100644
--- a/web/locales/zh/app.json
+++ b/web/locales/zh/app.json
@@ -5270,5 +5270,26 @@
"Move this knowledge base with its documents, settings, and indexes. Existing workspace assignments are updated.": "连同文档、设置和索引一起移动此知识库。现有工作区分配会同步更新。",
"Review move": "检查移动详情",
"{{count}} files · {{bytes}} bytes": "{{count}} 个文件 · {{bytes}} 字节",
- "Assignments updated: {{names}}": "将更新以下工作区的分配:{{names}}"
+ "Assignments updated: {{names}}": "将更新以下工作区的分配:{{names}}",
+ "Marks": "标记",
+ "Mark here": "在此标记",
+ "Use selection": "使用选区",
+ "Mark this subtitle": "标记此字幕",
+ "Suggest marks": "推荐标记",
+ "Suggested marks": "推荐标记",
+ "Delete mark": "删除标记",
+ "Filter marks": "筛选标记",
+ "Key point": "要点",
+ "Review later": "待复习",
+ "Reviewed": "已复习",
+ "Mark as reviewed": "标记为已复习",
+ "No marks yet.": "暂无标记。",
+ "Dismiss suggestion": "忽略推荐",
+ "Marks could not be loaded.": "无法加载标记。",
+ "Suggestions could not be loaded.": "无法加载推荐标记。",
+ "Mark was not saved.": "标记保存失败。",
+ "Mark was not deleted.": "标记删除失败。",
+ "Mark was not updated.": "标记更新失败。",
+ "Draft note or reason...": "备注或标记原因...",
+ "Save mark": "保存标记"
}
diff --git a/web/tests/video-learning-marks.test.ts b/web/tests/video-learning-marks.test.ts
new file mode 100644
index 000000000..e5e1438e0
--- /dev/null
+++ b/web/tests/video-learning-marks.test.ts
@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ filterMarks,
+ formatMarkRange,
+ locatorsForRange,
+ markCoversTime,
+ rangeFromCues,
+} from "../lib/video-learning-marks";
+
+const cues = [
+ { start: 1, end: 4, text: " first " },
+ { start: 5, end: 8, text: "second" },
+ { start: 9, end: 12, text: "third" },
+];
+
+const segments = cues.map((cue, index) => ({ ...cue, locator: index + 1 }));
+
+test("builds a subtitle range and maps it to segment locators", () => {
+ const range = rangeFromCues(cues, [2, 0, 2]);
+ assert.ok(range);
+ assert.equal(range.start_seconds, 1);
+ assert.equal(range.end_seconds, 12);
+ assert.equal(range.quote, "first third");
+ assert.deepEqual(locatorsForRange(segments, 2, 7), {
+ start_locator: 1,
+ end_locator: 2,
+ });
+});
+
+test("filters marks chronologically and matches point and range marks", () => {
+ const marks = [
+ {
+ mark_id: "b",
+ kind: "question" as const,
+ start_seconds: 8,
+ end_seconds: 8,
+ start_locator: 2,
+ end_locator: 2,
+ quote: "",
+ note: "",
+ author: "user" as const,
+ created_at: "2",
+ updated_at: "2",
+ },
+ {
+ mark_id: "a",
+ kind: "review" as const,
+ start_seconds: 1,
+ end_seconds: 4,
+ start_locator: 1,
+ end_locator: 1,
+ quote: "",
+ note: "",
+ author: "user" as const,
+ created_at: "1",
+ updated_at: "1",
+ },
+ ];
+ assert.deepEqual(filterMarks(marks, "all").map((mark) => mark.mark_id), [
+ "a",
+ "b",
+ ]);
+ assert.equal(filterMarks(marks, "review").length, 1);
+ assert.equal(markCoversTime(marks[0], 8.5), true);
+ assert.equal(markCoversTime(marks[1], 4.5), false);
+ assert.equal(formatMarkRange(marks[0]), "00:08");
+ assert.equal(formatMarkRange(marks[1]), "00:01 - 00:04");
+});