给任何 AI 助手或脚本看的规范:按它整理一个媒体文件夹并写 CARSCHOOL.md,CarSchool 就能读懂这个文件夹是什么、给谁听、怎么播。把这一页和文件夹一起交给助手,说「按 CarSchool 规范整理并写简介」即可。

CarSchool Folder Spec (v1)

How to lay out a media folder and describe it so CarSchool Media Player can index it, search it, and build playlists from it. Written for agents (Claude Code, ChatGPT, scripts) and humans alike. Think of it as the Jellyfin naming guide, but for a car-listening library.

Give an agent this file plus a folder and say: "Organize this folder per the CarSchool spec and write the summary." The prompt at the bottom is ready to paste.

---

1. Folder layout

<Library root>/                 ← one root per course, series, or collection
├── CARSCHOOL.md                ← required: what this library is
├── Week 01/
│   ├── CARSCHOOL.md            ← optional: only if the subfolder needs its own description
│   ├── 01 - Timeline Song - Week 01.mp3
│   └── 02 - Timeline Hand Motions - Week 01 - Explanation.mp4
├── Week 02/
│   └── ...
└── Extras/
    └── ...

Rules: - One root per thing you would name in a sentence ("CC Cycle 2", "2026 Sunday School", "Chinese stories for Mia"). Do not mix unrelated collections under one root. - Subfolders group by the unit the listener thinks in: week, lesson, month, chapter, speaker. Flat roots are fine for small collections. - Subfolders inherit the parent's CARSCHOOL.md. Add one to a subfolder only when it differs from the parent in purpose, audience, or ordering. - Keep depth ≤ 3. Deeper trees still index, but playlists read better when units are shallow.

2. Media file naming

Supported extensions: video mp4 mov m4v; audio mp3 m4a wav aac aiff aif caf flac. Anything else is ignored.

What the app parses out of a file name (case-insensitive):

Conventions: - Start with a two-digit sequence number when order matters: 01 -, 02 -. This is the single most useful thing you can do for playlists. - Keep the labels a listener would say out loud in the name: Week 3, Lesson 4, Cycle 2, 2026, Part 2. The app never strips them. - For recordings, put the date first: 2026-03-05 - Romans 8 - Pastor Chen.mp3. Sort and "last month" queries also use the file date, so keep the original file timestamp when moving files. - Use Title Case, not ALL CAPS. Separators: - between parts, spaces inside a part. - Do not rename files the user already labeled unless asked. Renaming loses per-file notes and play history in the app. - Vocabulary the app already recognizes as facets (use these words when they apply): subject English Grammar, Science, Timeline, Latin, History, Geography, Math; variant Piano, Piano Only, Harmony, In the Round, Complete; content type Hand Motions, Weekly Connections, Foundations at Home, Memory Work, Explanation.

3. CARSCHOOL.md

One per root (required). One per subfolder (optional). UTF-8, Markdown, a flat front-matter block followed by prose.

---
spec: 1
title: CC Cycle 2 Memory Work
language: en
audience: kids 6–9
contentType: songs, memory work
orderingRule: by week, then by sequence number
listenMode: loop
tags: [classical-conversations, cycle-2, weekly, school-run]
---
Weekly memory work songs for Classical Conversations Cycle 2, weeks 1–24.
Each week has a song (loop it) and an explanation version (listen once).
Weeks 1–12 are the fall semester, 13–24 spring.

## Folders
- Week 01 … Week 24 — one week each; songs first, explanations after
- Extras — review medleys, no week number

## Playlist hints
- "this week's songs" → the current week's folder, songs only
- "review last month" → the previous four weeks, songs only, shuffled
- Never mix explanations into a loop playlist

Front-matter fields

Unknown keys are kept but ignored. Values are plain text: no nested YAML, no quotes needed unless the value contains :.

Body

• First paragraph is the summary. Keep it under 300 characters. This is what the playlist planner reads. Say what it is, who it is for, and any rule that affects how it should be played.
• Optional sections, in this order, each a bullet list:
• ## Folders — one line per subfolder: - <folder name> — <what is in it>. Only for subfolders without their own CARSCHOOL.md.
• ## Files — one line per file that needs a note the name does not carry: - <file name> — <note>. Skip files whose name already says everything.
• ## Playlist hints — natural-language rules for building playlists from this folder: what pairs well, what must not be mixed, what "this week" means here.
• No marketing language, no headings other than the three above, no tables. Plain bullets parse best.

Writing rules for agents

1. Read before writing. List every media file, look at the folder names, open any existing README.md, SUMMARY.md, .nfo, or notes. If a CARSCHOOL.md already exists, update it; do not start over.
2. Describe what is there, not what could be. If you cannot tell whether the files are songs or lectures, say so in the summary and ask the user one question instead of guessing.
3. Never invent audience or language. Leave the field out if you are not sure.
4. Do not repeat the file list in the summary. The app already has the file list; the summary is for meaning.
5. Tags are for search, not for taxonomy. Five to ten words a person might actually say, in the languages the user speaks.
6. Only touch media files if the user asked you to organize them. Writing CARSCHOOL.md alone never requires renaming anything.

4. Precedence and updates

• Lookup order per folder: CARSCHOOL.md → README.md → SUMMARY.md. Only CARSCHOOL.md is ever written by the app; the other two are read as-is and never modified.
• The app keeps a copy of each card. Newest wins: if the file on disk is newer than the app's copy, the file replaces it on the next refresh; if the user edited in-app more recently, the app writes its copy back to CARSCHOOL.md (when the folder is writable).
• To correct a card, edit the file, edit it in the app, or re-run the agent with a one-line correction. All three converge on the same file.

5. Second example: recordings with useless file names

Before:

Sunday School 2026/
├── REC001.mp3
├── REC002.mp3
└── REC003.mp3

After the agent organizes it (user asked for renaming):

Sunday School 2026/
├── CARSCHOOL.md
├── 2026-01-11 - Romans 1 - Introduction.mp3
├── 2026-01-18 - Romans 1 - Verses 18-32.mp3
└── 2026-01-25 - Romans 2 - God's Judgment.mp3

---
spec: 1
title: Sunday School 2026 — Romans
language: zh-Hans
audience: adults
contentType: lecture
orderingRule: by date oldest first
listenMode: once
dateRange: 2026-01-11/2026-06-28
tags: [sunday school, romans, 主日学, 罗马书, sermon, 2026]
---
Weekly adult Sunday school on the book of Romans, Mandarin with some English
terms, roughly 45 minutes each. Listen in order; each week builds on the last.

## Playlist hints
- "catch up" → all lessons after the last one marked played, oldest first
- Pairs well with nothing else; keep as its own list

6. Prompt to paste into an agent

Read docs/CARSCHOOL-FOLDER-SPEC.md, then look at the folder at <PATH>.
List the media files and subfolders, tell me in two sentences what this
collection is, then write <PATH>/CARSCHOOL.md following the spec exactly
(spec: 1 front matter, summary paragraph under 300 characters, optional
Folders / Files / Playlist hints sections). Do not rename or move any media
file unless I say so. If the purpose or audience is unclear, ask me one
question before writing.

中文版：

先读 docs/CARSCHOOL-FOLDER-SPEC.md，再看 <PATH> 这个文件夹。
列出里面的媒体文件和子目录，用两句话告诉我这是什么，然后严格按规范写
<PATH>/CARSCHOOL.md（spec: 1 的 front matter，摘要段落 300 字以内，
可选的 Folders / Files / Playlist hints 三节）。除非我明确要求，不要改名
或移动任何媒体文件。用途或受众不清楚就先问我一个问题再写。

Source of truth: docs/CARSCHOOL-FOLDER-SPEC.md in the app repository. Questions: info@chenacademy.org