Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](ht
## [Unreleased]

### Added
- Data saver: a header switch (automatic on Save-Data and 2G/3G) that serves lighter Cloudinary renditions and the `sd` streaming ladder; 33–76% fewer bytes measured (Phase 21)
- Concept Map `/concepts` and Compare view `/concepts/[key]`: the same concept from every teacher as one Compare Reel (Phase 19)
- Cloudinary asset index: tags and contextual metadata on each session's asset, synced from the Studio and read back with the Search API (Phase 19)

Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ Colleges, clubs and coaching institutes record hundreds of hours of lectures and
| **Answer Reels** | The moments an answer cites, from different speakers and sessions, stitched into one labelled video. |
| **Concept Map** | `/concepts` lines up every concept your lectures teach and how many different teachers explain it. Open one and hear the same idea from each lecturer, back to back, as one Cloudinary-spliced video, until one explanation clicks. |
| **Learning Paths** | `/learn`: type a topic and get a 3–5 step course, ordered basics first, drawn from moments across the library and edited into one video. |
| **Data saver** | One switch (and automatic on Save-Data or 2G/3G) serves smaller, lower-quality Cloudinary renditions: thumbnails 76% lighter, clips and reels 38–41%, and a streaming ladder that tops out at 0.9 Mbps instead of 3.4. Built for India’s mobile data. |
| **Study Packs** | Every session gets a summary, key concepts, a quiz whose explanations **play the moment** the teacher explains it, and a "Session in 60 seconds" highlight reel. Pravaha generates them automatically from the transcript. |
| **Moments** | One tap turns any cited clip into a vertical, AI-cropped, subtitled short for WhatsApp or Instagram, with its own share page and preview card. The short is just a Cloudinary URL; nothing is rendered. |
| **Insights** | Organizers see what learners ask, the **knowledge gaps** the library can't answer yet (what to record next), and which Moments get shared. Every report downloads as CSV. Visitors can explore a read-only demo of the Studio. |
Expand Down Expand Up @@ -121,6 +122,7 @@ Cloudinary isn't just storage here; the product depends on it.
| `e_preview:duration_6` | **AI hover previews** on library cards: the session's most interesting moments in 6 silent seconds |
| `so_`/`eo_` + `c_fill,ar_9:16,g_auto` + timed `l_text` captions + `f_auto,q_auto` | **Moments**: trimmed, subject-tracked, subtitled vertical clips |
| `g_auto` thumbnails and poster frames | Content-aware library cards, results and social preview cards |
| `q_auto:low`, `c_limit`/`w_` sizing, `sp_sd` streaming profile | **Data saver**: every video, reel, thumbnail and the HLS ladder re-requested lighter for slow or metered connections |
| `l_video:…,fl_splice` + timed `l_text` labels | **Answer Reels** and **Session in 60 seconds**: moments from one or more sessions stitched into one video |
| Webhooks (`notification_url`, signature-verified) | Upload → transcribed → `ready` with no polling |
| Incoming transformation `eo_60` on a second signed preset | **Try it** uploads: Cloudinary keeps only the first 60 seconds, so a public upload can't cost more |
Expand Down
1 change: 1 addition & 0 deletions docs/CLOUDINARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ Learner (browser) ◀── HLS adaptive stream · Moment clips · g_auto thumbn
|---|---|---|
| Ingest | Signed direct upload (Upload Widget) | Large-file upload handling + object storage |
| Watch | `auto_transcription` | A speech-to-text pipeline (Whisper on GPUs) |
| Watch | `sp_sd` streaming profile, `q_auto:low`, `w_`/`c_limit` sizing | A second, lower-bitrate encode of the whole library and a client-side switch between them |
| Watch | `auto_chaptering` | A chaptering model |
| Watch | Video Player: HLS adaptive streaming, chapters, subtitles | An encoding ladder (FFmpeg) + HLS packaging + a player |
| Find / Ask | The transcript is the corpus both pillars search | Our own STT output |
Expand Down
2 changes: 1 addition & 1 deletion docs/COST.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Every figure is tagged **ACTUAL** (by design / confirmed plan mechanics), **ESTI

| Service | Tier | Tag | Notes |
|---|---|---|---|
| Cloudinary | Free — 25 credits/month (1 credit = 1,000 transformations, 1 GB storage or 1 GB bandwidth); 100 MB per video | **ACTUAL** (Oct 2 usage check) | Video processing is the heavy item: each SD second counts 2 transformations, each HD second 4. Testing on two short clips used 11.2 credits. An HLS ladder multiplies that per rendition, so the player uses `hd_lean` (720p/360p/180p) instead of `full_hd`'s six renditions: roughly 8 transformations per second of video instead of about 16. The demo library is sized to fit: ~6 sessions of 2–3 minutes |
| Cloudinary | Free — 25 credits/month (1 credit = 1,000 transformations, 1 GB storage or 1 GB bandwidth); 100 MB per video | **ACTUAL** (Oct 2 usage check) | Video processing is the heavy item: each SD second counts 2 transformations, each HD second 4. Testing on two short clips used 11.2 credits. An HLS ladder multiplies that per rendition, so the player uses `hd_lean` (720p/360p/180p) instead of `full_hd`'s six renditions: roughly 8 transformations per second of video instead of about 16. The demo library is sized to fit: ~6 sessions of 2–3 minutes. Data saver adds a second, lighter `sd` ladder per session, generated the first time someone views it in that mode |
| Google Gemini (Flash / Flash-Lite) | Free tier / pay-as-you-go | **ASSUMPTION** | ~2–3k tokens per Ask; Flash-class pricing is a fraction of a cent per Ask; a few hundred Asks during build + judging. Hard-bounded by the app rate limits (60/h/IP, 500/day) **and** a budget alert in Google AI Studio / Cloud billing |
| Neon Postgres | Free | **ESTIMATE** | Thousands of segment rows ≈ a few MB |
| Vercel | Hobby | **ESTIMATE** | Demo traffic is tiny; Ask's `maxDuration` (30 s) and Study Packs' (60 s) fit Hobby function limits |
Expand Down
2 changes: 2 additions & 0 deletions docs/DEMO.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ Never show setup, code, dashboards or waiting. Every shot is the problem, the pr
| 2:24–2:35 | **Cloudinary under the hood** panel on the answer: each URL step explained | "Every clip, reel and short is a Cloudinary transformation, and Pravaha shows exactly which." |
| 2:35–2:45 | Architecture strip: Cloudinary (transcription · chaptering · streaming · g_auto · e_preview · transformations) + Pravaha (retrieval · grounded Ask · Moments · Insights) · team | "Cloudinary turns video into data. Pravaha turns data into answers you can watch. Code Blooded, Track 3." |

**Bonus shot (if there is time):** header → **Data saver** on → the same answer reel and thumbnails reload visibly lighter. Voice-over: "Built for India’s mobile data: one switch, and Cloudinary serves everything at a fraction of the bytes."

## Pre-Recording Checklist

- **Cloudinary credits first** (free plan: 25 a month). Check usage before recording. New uploads, new answer clips, reels and Moments cost credits; already-generated URLs don't. If usage is near the limit, upgrade first. If you can't, film the upload shot from an existing recording, and ask only questions that have been asked before (their clips are cached).
Expand Down
1 change: 1 addition & 0 deletions docs/IMPLEMENTATION_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,3 +94,4 @@ The core loop (Phases 01–09) is built and verified on real Cloudinary + Neon.

| 18 | Query understanding, Learning Paths, AI reliability | Rewrite questions into the library's words (and translate them), honest near-miss answers, `/learn` micro-courses as one Cloudinary reel, circuit breaker + deep health | ✅ done (Oct 3) |
| 19 | Concept Map & Cloudinary asset index | Same concept, every teacher, as one Compare Reel; tags + contextual metadata on Cloudinary assets, read back with the Search API | ✅ done (Oct 3) |
| 21 | Data saver | Light Cloudinary renditions (35–76% fewer bytes, sd streaming ladder) for slow or metered connections; follows Save-Data and 2G/3G automatically | ✅ done (Oct 3) |
27 changes: 27 additions & 0 deletions docs/phases/PHASE-21-data-saver.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Phase 21 — Data saver

**Status: DONE (Oct 3)** · branch `feature/data-saver-mode`

## Why
Most learners in India watch on mobile data that is slow, metered, or both. A 720p lecture stream and a full-size clip can cost more than a student wants to spend on one question. Cloudinary can serve any asset at any size and quality from one public id, so the fix is a choice of URL, not a second copy of the library.

## What shipped
- **One rewrite, `liteUrl()`** (`src/lib/media.ts`): turns any Cloudinary URL Pravaha builds into its light version. Frames halve (reels 1280×720 → 640×360, Moments 720 → 360 wide, thumbnails and previews 640 → 320), `q_auto` becomes `q_auto:low`, original-framing clips are capped at 640 wide, and burned-in captions and labels shrink with the frame so they stay in proportion. It lives beside the builders whose constants it mirrors, and tests build real URLs and check the result.
- **Player:** streams the `sd` ladder (top rendition 931 kbps, against 3.4 Mbps for `hd_lean`) and skips the seek-bar sprite and highlights graph, two extra downloads. The player is created only after the mode is known, so a slow connection never starts on the full ladder.
- **Library cards** stop loading hover previews.
- **Switch** in the header. With nothing stored it follows the browser: it turns on by itself for Save-Data and 2G/3G connections. The choice is remembered on this device only (`src/lib/data-saver.ts`).

## Measured on real Cloudinary output
| Asset | Full | Data saver | Saved |
|---|---|---|---|
| Thumbnail | 46.7 KB | 11.2 KB | 76% |
| Clip (original framing) | 397.6 KB | 233.5 KB | 41% |
| Answer / Compare reel (2 clips) | 794.6 KB | 490.0 KB | 38% |
| Moment (vertical, captioned) | 344.2 KB | 223.6 KB | 35% |
| Hover preview | 145.0 KB | 97.4 KB | 33% |
| Streaming ladder, top rendition | 3.4 Mbps | 0.93 Mbps | 73% |

Browser-checked: the switch flips thumbnails `w_640,q_auto` → `w_320,q_auto:low`, reels to 640×360, and the player requests `sp_sd` / `br_sd480` instead of `sp_hd_lean` / `br_hd720`.

## Cost note
The first light view of a session generates the `sd` ladder once (extra transformation credits); after that it is CDN-cached like everything else. Light renditions are smaller, so they cost less bandwidth.
2 changes: 2 additions & 0 deletions src/app/layout.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import type { Metadata, Viewport } from "next";
import { Inter } from "next/font/google";
import Link from "next/link";

import { DataSaverToggle } from "@/components/DataSaverToggle";
import { LogoMark } from "@/components/Logo";
import { SearchShortcut } from "@/components/SearchShortcut";
import { SiteChrome } from "@/components/SiteChrome";
Expand Down Expand Up @@ -72,6 +73,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
>
Try it
</Link>
<DataSaverToggle />
<ThemeToggle />
</div>
</nav>
Expand Down
12 changes: 8 additions & 4 deletions src/components/AskAnswer.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import { MomentButton } from "@/components/MomentButton";
import { UnderTheHood } from "@/components/UnderTheHood";
import { Snippet } from "@/components/ResultCard";
import { SaveButton } from "@/components/SaveButton";
import { useLiteUrl } from "@/lib/data-saver";
import { formatTime } from "@/lib/format";
import type { SnippetPart } from "@/lib/highlight";
import type { TimedWord } from "@/lib/segments";
Expand Down Expand Up @@ -245,6 +246,7 @@ const VOTE_KEY = (id: string) => `pravaha-vote-${id}`;

// Perplexity-style action bar under an answer: what it was built from, then Share, Copy and 👍/👎.
function AnswerActions({ data, question }: { data: Extract<AskResponse, { status: "answered" }>; question: string }) {
const lt = useLiteUrl();
const [copied, setCopied] = useState<"link" | "text" | null>(null);
const [vote, setVote] = useState<"up" | "down" | null>(null);
const answerId = data.answerId ?? null;
Expand Down Expand Up @@ -310,7 +312,7 @@ function AnswerActions({ data, question }: { data: Extract<AskResponse, { status
{data.citations.slice(0, 3).map((c) => (
<Image
key={c.segmentId}
src={thumbUrl(c.publicId, c.startS)}
src={lt(thumbUrl(c.publicId, c.startS))}
alt=""
width={48}
height={48}
Expand Down Expand Up @@ -411,8 +413,9 @@ function FollowUps({ questions, onAsk }: { questions: string[]; onAsk?: (questio
// The cited moments stitched into one video by Cloudinary — watch the whole answer, across sessions.
function AnswerReel({ reel }: { reel: NonNullable<Reel> }) {
const [playing, setPlaying] = useState(false);
const lt = useLiteUrl();
if (playing) {
return <video src={reel.url} className="rise mt-5 aspect-video w-full rounded-2xl bg-black" controls autoPlay playsInline />;
return <video src={lt(reel.url)} className="rise mt-5 aspect-video w-full rounded-2xl bg-black" controls autoPlay playsInline />;
}
return (
<button
Expand Down Expand Up @@ -499,15 +502,16 @@ function AnswerText({ text, citations }: { text: string; citations: Citation[] }

function CitationCard({ c }: { c: CitationGroup<Citation> }) {
const [playing, setPlaying] = useState(false);
const lt = useLiteUrl();
return (
<article className="lift h-full rounded-2xl border border-border bg-bg p-3">
<div className="relative overflow-hidden rounded-xl bg-black">
{playing ? (
<video src={clipUrl(c.publicId, c.startS, c.endS)} className="aspect-video w-full" controls autoPlay playsInline />
<video src={lt(clipUrl(c.publicId, c.startS, c.endS))} className="aspect-video w-full" controls autoPlay playsInline />
) : (
<button type="button" onClick={() => setPlaying(true)} className="group block w-full" aria-label={`Play ${c.title} at ${formatTime(c.startS)}`}>
<Image
src={thumbUrl(c.publicId, c.startS)}
src={lt(thumbUrl(c.publicId, c.startS))}
alt=""
width={640}
height={360}
Expand Down
4 changes: 3 additions & 1 deletion src/components/ConceptView.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import Link from "next/link";
import { MomentButton } from "@/components/MomentButton";
import { ReelPlayer } from "@/components/ReelPlayer";
import type { ConceptView as Concept } from "@/lib/concepts";
import { useLiteUrl } from "@/lib/data-saver";
import { formatTime } from "@/lib/format";
import { reelUrl, thumbUrl } from "@/lib/media";

Expand All @@ -15,6 +16,7 @@ const firstName = (speaker: string | null, title: string) => (speaker ?? title).
// video (each clip labelled with who is speaking) and as cards that open the full session.
export function ConceptView({ concept }: { concept: Concept }) {
const { moments } = concept;
const lt = useLiteUrl();
const reel = reelUrl(moments.map((m, i) => ({ publicId: m.publicId, startS: m.startS, endS: m.endS, label: `${i + 1} · ${firstName(m.speaker, m.title)}` })));
const teachers = new Set(moments.map((m) => m.speaker ?? m.lectureId)).size;

Expand All @@ -33,7 +35,7 @@ export function ConceptView({ concept }: { concept: Concept }) {
<li key={m.segmentId} className="flex flex-col rounded-2xl border border-border bg-surface p-3">
<Link href={`/watch/${m.lectureId}?t=${Math.floor(m.startS)}`} className="relative block overflow-hidden rounded-xl">
<Image
src={thumbUrl(m.publicId, m.startS)}
src={lt(thumbUrl(m.publicId, m.startS))}
alt={`${m.title}, at ${formatTime(m.startS)}`}
width={640}
height={360}
Expand Down
26 changes: 26 additions & 0 deletions src/components/DataSaverToggle.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
"use client";

import { setDataSaver, useDataSaver } from "@/lib/data-saver";

// Header switch for data saver (src/lib/data-saver.ts). Starts on by itself for Save-Data and 2G/3G connections.
export function DataSaverToggle() {
const on = useDataSaver();
const label = on ? "Data saver is on: smaller videos and images. Turn off" : "Turn on data saver: smaller videos and images";
return (
<button
type="button"
onClick={() => setDataSaver(!on)}
aria-pressed={on}
aria-label={label}
title={label}
className={`grid h-9 place-items-center rounded-lg px-2 text-xs font-semibold hover:bg-surface ${on ? "bg-accent/10 text-accent" : "text-muted hover:text-fg"}`}
>
<span className="flex items-center gap-1">
<svg viewBox="0 0 24 24" className="size-4" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" aria-hidden>
<path d="M12 3v12m0 0-4-4m4 4 4-4M5 21h14" />
</svg>
<span className="hidden sm:inline">{on ? "Lite" : "Data saver"}</span>
</span>
</button>
);
}
4 changes: 3 additions & 1 deletion src/components/LearningPathView.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,15 @@ import Link from "next/link";

import { MomentButton } from "@/components/MomentButton";
import { ReelPlayer } from "@/components/ReelPlayer";
import { useLiteUrl } from "@/lib/data-saver";
import { formatTime } from "@/lib/format";
import { thumbUrl } from "@/lib/media";
import type { LearningPath } from "@/lib/paths";

// A Learning Path: the whole course as one Cloudinary-stitched video, then each step as a card that explains
// why it comes next and opens the full session at that second.
export function LearningPathView({ path }: { path: LearningPath }) {
const lt = useLiteUrl();
const sessions = new Set(path.steps.map((s) => s.lectureId)).size;
const speakers = [...new Set(path.steps.map((s) => s.speaker).filter(Boolean))];

Expand Down Expand Up @@ -51,7 +53,7 @@ export function LearningPathView({ path }: { path: LearningPath }) {
<div className="mt-3 flex gap-3 rounded-2xl border border-border bg-bg p-3">
<Link href={`/watch/${step.lectureId}?t=${Math.floor(step.startS)}`} className="relative block w-28 shrink-0 overflow-hidden rounded-xl sm:w-36">
<Image
src={thumbUrl(step.publicId, step.startS)}
src={lt(thumbUrl(step.publicId, step.startS))}
alt={`${step.title}, at ${formatTime(step.startS)}`}
width={288}
height={162}
Expand Down
9 changes: 6 additions & 3 deletions src/components/LibraryCard.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import { useState } from "react";

import { formatTime } from "@/lib/format";
import type { Lecture } from "@/lib/lectures";
import { useDataSaver, useLiteUrl } from "@/lib/data-saver";
import { posterTime, previewUrl, thumbUrl } from "@/lib/media";

// A library card that plays Cloudinary's AI preview of the session while hovered or focused. The video is
Expand All @@ -15,9 +16,11 @@ export function LibraryCard({ lecture, index }: { lecture: Lecture; index: numbe
const [active, setActive] = useState(false);
const [shown, setShown] = useState(false);
const [failed, setFailed] = useState(false);
const lt = useLiteUrl();
const lite = useDataSaver();

function start() {
if (failed || !previewsAllowed()) return;
if (failed || lite || !previewsAllowed()) return;
setActive(true);
}
function stop() {
Expand All @@ -37,14 +40,14 @@ export function LibraryCard({ lecture, index }: { lecture: Lecture; index: numbe
>
<div className="lift relative overflow-hidden rounded-2xl bg-border">
<Image
src={thumbUrl(lecture.publicId, posterTime(lecture.durationS))}
src={lt(thumbUrl(lecture.publicId, posterTime(lecture.durationS)))}
alt=""
width={640}
height={360}
unoptimized // Cloudinary already serves f_auto,q_auto
className="aspect-video w-full object-cover transition-transform duration-300 group-hover:scale-[1.02]"
/>
{active && (
{active && !lite && (
<video
src={previewUrl(lecture.publicId)}
muted
Expand Down
Loading
Loading