# MandarinClips

> Authentic Chinese cinema dialogue corpus for Mandarin language learners and educators.

MandarinClips is an immersion-focused Chinese language learning platform and pedagogical API built from authentic Chinese movies and television series. It provides English-speaking learners and TCSL (Teaching Chinese as a Second Language) educators with a sentence-level cinematic dialogue concordancer to bridge the gap between classroom textbooks and real-world spoken Chinese.

Learners and AI agents can search any Chinese phrase, vocabulary item, or grammar pattern and instantly study how native speakers naturally use it across diverse cinematic contexts with multi-turn dialogue alignments.

## Overview & Verified Scale

* Live Dialogue Clips: 182,404 curated video clips (~3 seconds each, single-sentence focus with 3-turn context)
* Spoken Dialogue Lines: 412,323 verified lines of dialogue
* Primary Interface Language: English (served directly at the root `/` domain)
* Pedagogical Framework: Schema.org LearningResource, DefinedTerm, and official HSK 3.0 standards

## Model Context Protocol (MCP) & AI Integration

MandarinClips natively supports the open Model Context Protocol (MCP), enabling Claude Desktop, Cursor, and web-based AI agents to query the cinema corpus programmatically:

* Official MCP Registry Namespace: `com.mandarinclips/mcp` (v1.1.0 Verified)
* Streamable HTTP / SSE Endpoint: https://www.mandarinclips.com/mcp
* NPM CLI Package: `mandarinclips-mcp` (v1.1.0)
* Available Tools:
  - `search_dialogue_clips`: Search 180,000+ authentic cinema lines by Chinese/Pinyin with 3-turn conversational context (Previous, Target, Next) and English pragmatic subtext.
  - `get_hsk_vocabulary`: Retrieve official HSK 3.0 vocabulary details, definitions, and cinema video examples.
  - `get_grammar_pattern`: Look up Chinese grammar structures, visual slot formulas, and spoken variations.

## Core Capabilities

* Multi-Modal Contextual Tracks: Simultaneous display of Simplified Chinese characters, standardized Pinyin with tone marks, natural English translations, and native video turn sequences.
* Bilingual Full-Text Search: Powered by PostgreSQL PGroonga and pg_trgm GIN indexes, supporting Simplified Chinese characters (e.g., 算了, 应该的) and untoned lowercase Pinyin (e.g., "suan le ba", "ni hao").
* HSK 3.0 Proficiency Indexing: Graded across all official HSK 3.0 bands (Levels 1 through 7-9).
* 10-Dimensional Pragmatic Context: Controlled scene taxonomies (workplace, dining, social, family, conflict, etc.), native English pragmatic subtext (speaker's actual intent vs. literal wording), communicative speech styles, and registers.
* Non-Linear Semantic Knowledge Graph: Directed graph relations connecting similar expressions, contrastive retorts, and pragmatic alternatives.
* Instant Audio Shadowing & Looping: Zero-latency browser-based native playback designed for pronunciation and rhythm training.

## Core Content Hubs (Canonical Clean Routes)

All active content is served directly under root-level canonical routes without `/en/` prefixes:

* Homepage & Discovery: https://www.mandarinclips.com/
* HSK 3.0 Vocabulary Atlas: https://www.mandarinclips.com/hsk
* Conversational Expressions: https://www.mandarinclips.com/expressions
* Sentence Blueprints (Grammar): https://www.mandarinclips.com/grammar
* Pragmatic Communicative Scenes: https://www.mandarinclips.com/scenes
* TV Shows & Movies Directory: https://www.mandarinclips.com/shows
* Unified Cinema Corpus Search: https://www.mandarinclips.com/search
* Educational Insights & Blog: https://www.mandarinclips.com/blog/
* Academic Access for Professors: https://www.mandarinclips.com/educators

## URL & Canonical Conventions

Individual clip, word, and grammar dossiers follow strict SEO/GEO friendly slug patterns:

* Clip Dossier: https://www.mandarinclips.com/clip/{clip_id}
  Example: https://www.mandarinclips.com/clip/1a6bc231-wei-mian-tai-qing-le-ba-1373000
* HSK Word Dossier: https://www.mandarinclips.com/word/{slug}
  Example: https://www.mandarinclips.com/word/ai-1
* Grammar Blueprint: https://www.mandarinclips.com/grammar/{slug}
  Example: https://www.mandarinclips.com/grammar/hai-shi-ba
* Pragmatic Scene Hub: https://www.mandarinclips.com/scenes/{scene_code}
  Example: https://www.mandarinclips.com/scenes/polite-refusal

Legacy multilingual paths (such as /zh/, /de/, /es/, /fr/, /ja/, /ko/) are permanently retired with HTTP 410 Gone status. Historical `/en/*` routes are permanently redirected via HTTP 301 to clean root URLs.

## Target Audience

* English-speaking self-learners bridging textbook theory into authentic spoken fluency.
* TCSL / CSL (Teaching Chinese as a Second Language) educators and university professors creating lesson plans and sourcing authentic example sentences.
* Advanced HSK students mastering nuanced modal particles, colloquial hedging, and cultural subtexts.
* NLP researchers, lexicographers, and AI agent builders requiring verified Chinese cinema dialogue alignments.

## Platform & Policies

* Website: https://www.mandarinclips.com
* Creator Mission: "Learn Chinese from real conversations instead of textbook sentences."
* Account & API Key Management: https://www.mandarinclips.com/account
* Fair Use & DMCA Notice: https://www.mandarinclips.com/fair-use
* Privacy Policy: https://www.mandarinclips.com/privacy
* Terms of Service: https://www.mandarinclips.com/terms