Especificació TSV per Importació YouTube

Relacionat amb: Sistema d'Importació
Objectiu: Definir el format de fitxer per a agents externs que generin dades de balls des de YouTube.

1. Introducció

Aquest document descriu l'especificació completa per generar un fitxer d'importació de balls des de YouTube cap a la plataforma Line Dance Platform. Està pensat perquè un agent extern (IA o humà) pugui generar fitxers compatibles amb el sistema d'importació.

Separador Recomanat

Usa TSV (Tab-Separated Values) amb extensió .tsv:

El tabulador (\t) rarament apareix als textos de descripcions
Millor que CSV amb comes o punts i coma
Tots els camps de text van entre cometes dobles (") per si contenen salts de línia o tabuladors

Alternativa: Si prefereixes CSV, usa cometes dobles per a tots els camps text i escapa les cometes internes ("")

Encoding: UTF-8 (obligatori)

2. Camps del Fitxer TSV/CSV

📹 Identificadors YouTube (per embebuts, imatges, etc.)

Camp	Tipus	Descripció	Exemple
`video_id`	String	ID del vídeo YouTube	`dQw4w9WgXcQ`
`video_url`	String	URL completa del vídeo	`https://www.youtube.com/watch?v=dQw4w9WgXcQ`
`video_title`	String	Títol original del vídeo	`"Never Gonna Line Dance - Teach & Demo"`
`video_description`	String	Descripció completa (text lliure)	`"Chorégraphie: Magali Chabret..."`
`channel_id`	String	ID del canal	`UCxxx123`
`channel_name`	String	Nom del canal	`LineDanceFR`
`published_at`	ISO 8601	Data publicació	`2024-03-15T10:30:00Z`
`thumbnail_default`	URL	Thumbnail 120x90	`https://i.ytimg.com/vi/.../default.jpg`
`thumbnail_medium`	URL	Thumbnail 320x180	`https://i.ytimg.com/vi/.../mqdefault.jpg`
`thumbnail_high`	URL	Thumbnail 480x360	`https://i.ytimg.com/vi/.../hqdefault.jpg`
`thumbnail_maxres`	URL	Thumbnail 1280x720 (si disponible)	`https://i.ytimg.com/vi/.../maxresdefault.jpg`
`duration`	ISO 8601	Durada del vídeo	`PT3M45S`
`view_count`	Integer	Nombre de visualitzacions	`15234`
`like_count`	Integer	Nombre de likes	`423`
`tags`	String	Tags del vídeo (separats per `	`)

💃 Dades del Ball (extretes del títol/descripció)

Camp	Tipus	Obligatori	Descripció	Exemple
`dance_name`	String	✅ SÍ	Nom del ball	`Never Gonna Line Dance`
`dance_counts`	Integer	No	Total counts	`64`
`dance_walls`	Integer	No	Nombre de parets	`2`
`dance_level`	Enum	No	Nivell del ball	`BEGINNER`, `INTERMEDIATE`, `ADVANCED`, `EXPERT`
`dance_year`	Integer	No	Any de creació	`2024`
`dance_description`	String	No	Descripció curta	`"Ball animat perfecte per a festes"`

👤 Coreògraf

Camp	Tipus	Descripció	Exemple
`choreographer_name`	String	Nom del coreògraf (múltiples separats per `	`)
`choreographer_country`	String	País codi ISO (múltiples separats per `	`)
`choreographer_isGroup`	Boolean	Si és grup o persona	`true` o `false`

🎵 Cançó (per buscar a iTunes API)

Camp	Tipus	Descripció	Exemple
`song_title`	String	Títol de la cançó	`Never Gonna Give You Up`
`song_artist`	String	Artista/intèrpret	`Rick Astley`
`song_year`	Integer	Any de la cançó (opcional)	`1987`
`song_bpm`	Integer	BPM si es coneix (opcional)	`113`

🔗 Tipus de Vídeo

Camp	Tipus	Descripció	Valors possibles
`link_kind`	Enum	Tipus de vídeo	`YOUTUBE_TEACH`, `YOUTUBE_DANCE`, `YOUTUBE_MUSIC`

📝 Especificació (bloc de text lliure)

Camp	Tipus	Descripció	Exemple
`imported_stepsheet`	String	Bloc complet de components + seqüència	`"Comptes: A(32)+B(16)+Tag(8) Phrasé: AA,BB,Tag"`

3. Header del Fitxer TSV

video_id	video_url	video_title	video_description	channel_id	channel_name	published_at	thumbnail_default	thumbnail_medium	thumbnail_high	thumbnail_maxres	duration	view_count	like_count	tags	dance_name	dance_counts	dance_walls	dance_level	dance_year	dance_description	choreographer_name	choreographer_country	choreographer_isGroup	song_title	song_artist	song_year	song_bpm	link_kind	imported_stepsheet

4. Exemple de Fila TSV

dQw4w9WgXcQ	https://www.youtube.com/watch?v=dQw4w9WgXcQ	"Never Gonna Line Dance - Teach & Demo"	"Chorégraphie: Magali Chabret (FR)..."	UCxxx123	LineDanceFR	2024-03-15T10:30:00Z	https://i.ytimg.com/vi/dQw4w9WgXcQ/default.jpg	https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg	https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg	https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg	PT4M32S	15234	423	linedance|country|tutorial	Never Gonna Line Dance	64	2	INTERMEDIATE	2024		Magali Chabret	FR	false	Never Gonna Give You Up	Rick Astley	1987	113	YOUTUBE_TEACH	"Comptes: A(32)+B(16)+Tag(8) Phrasé: AA,BB,Tag,AA,BB"

5. Exemples de `imported_stepsheet`

El camp imported_stepsheet conté el bloc de text lliure amb la informació de components i seqüència, tal com s'extreu de la descripció del vídeo:

Exemple 1:

Comptes : Partie A (32) + Partie B (16) + Tag (8)
Phrasé : AA, BB, AA, BB, Tag, AA, BB

Exemple 2:

Counts: A (32) + B (32) + C (16) + Bridge (8)
Sequence: A, B, C, A, B, Bridge, C, A, B

Exemple 3:

Comptes: Intro (16) + Part A (32) + Part B (32) + Tag (4)
Seqüència: Intro, A, B, Tag, A, B, B, Tag

Exemple 4:

Counts: 64 (2 walls)
Sequence: A, A, B, A, Tag, B, A, A

Exemple 5:

Comptes: 32
Seqüència: A, B, A, B, Tag, A, B

Exemple 6:

Counts: A (32), B (16), C (32), Tag (8)
Sequence: A, B, C, Tag, A, B, C, Tag

6. Recursos YouTube per al Software

Recurs	Com obtenir-lo	Per a què serveix
Thumbnail	`https://i.ytimg.com/vi/{VIDEO_ID}/maxresdefault.jpg`	Mostrar imatge del ball
Embed	`https://www.youtube.com/embed/{VIDEO_ID}`	Vídeo embebut a l'app
Canal	`channel_id` + `channel_name`	Atribució i links al canal
Durada	`contentDetails.duration`	Mostrar durada del vídeo
Estadístiques	`statistics.viewCount`, `likeCount`	Popularitat/relevància

Thumbnails sense API

Les thumbnails es poden construir sense API només amb el video_id:

Default (120x90): https://i.ytimg.com/vi/{ID}/default.jpg
Medium (320x180): https://i.ytimg.com/vi/{ID}/mqdefault.jpg
High (480x360): https://i.ytimg.com/vi/{ID}/hqdefault.jpg
MaxRes (1280x720): https://i.ytimg.com/vi/{ID}/maxresdefault.jpg

7. Flux de Treball per l'Agent Extern

┌─────────────────────────────────────────────────────────────────────────────┐
│                     FLUX D'OBTENCIÓ I GENERACIÓ TSV                         │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1️⃣ ENTRADA                                                                 │
│  ─────────────────────────────────────────────────────────────────────────  │
│  • Llista d'URLs de YouTube (o cerca per canal/playlist)                    │
│                                                                             │
│  2️⃣ OBTENCIÓ DADES YOUTUBE                                                  │
│  ─────────────────────────────────────────────────────────────────────────  │
│  • Crida YouTube Data API v3:                                               │
│    - videos.list(part=snippet,contentDetails,statistics)                    │
│  • Guarda: video_id, títol, descripció, thumbnails, durada, stats, etc.    │
│                                                                             │
│  3️⃣ PARSEIG DEL TÍTOL I DESCRIPCIÓ (IA o regex)                            │
│  ─────────────────────────────────────────────────────────────────────────  │
│  • Extreu: nom ball, coreògraf, país, nivell, counts, walls                │
│  • Extreu: títol cançó, artista                                            │
│  • Extreu: bloc de components + seqüència → imported_stepsheet             │
│  • Determina: link_kind (TEACH si és tutorial, DANCE si és demo, etc.)     │
│                                                                             │
│  4️⃣ GENERACIÓ TSV                                                           │
│  ─────────────────────────────────────────────────────────────────────────  │
│  • Una fila per vídeo                                                       │
│  • Camps de text entre cometes dobles                                       │
│  • Encoding UTF-8                                                           │
│                                                                             │
│  5️⃣ SORTIDA                                                                 │
│  ─────────────────────────────────────────────────────────────────────────  │
│  • Fitxer: youtube_import_YYYYMMDD.tsv                                      │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

8. Mapeig TSV → Base de Dades

Camp TSV	Taula destí	Camp destí	Notes
`dance_name`	DANCE	name	Obligatori
`dance_counts`	DANCE	counts	Opcional
`dance_walls`	DANCE	walls	Opcional
`dance_level`	DANCE	level_id	Fer lookup per nom
`dance_year`	DANCE	originYear	Opcional
`dance_description`	DANCE	description	Opcional
`choreographer_name`	CHOREOGRAPHER	name	Find-or-create
`choreographer_country`	CHOREOGRAPHER	country	Opcional
`choreographer_isGroup`	CHOREOGRAPHER	isGroup	Default: false
`song_title` + `song_artist`	SONG	(via iTunes API)	Cerca iTunes, vincula
`video_url`	LINK	url
`link_kind`	LINK	kind
`video_id`	LINK	videoId	Per embebuts/thumbnails
`imported_stepsheet`	LINE_DANCE_SPEC	importedStepsheet	Text lliure
`thumbnail_high`	LINK o DANCE	(camp calculat)	Per mostrar imatge

9. Model de Dades de Referència

┌─────────────────────────────────────────────────────────────────────────────┐
│                                   DANCE                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│ • name (obligatori)      ← Nom del ball extret del títol o descripció      │
│ • counts (Integer)       ← Total counts principals (opcional, per filtres) │
│ • walls (Integer)        ← Nombre de parets                                │
│ • level_id (FK)          ← Nivell (BEGINNER, INTERMEDIATE, etc.)           │
│ • description (TEXT)     ← Descripció curta/manual                         │
│ • originYear (Integer)   ← Any de creació                                  │
└───────────────────────────────┬─────────────────────────────────────────────┘
                                │
       ┌────────────────────────┼────────────────────────┐
       ▼                        ▼                        ▼
┌──────────────────┐   ┌────────────────────┐   ┌─────────────────┐
│  CHOREOGRAPHER   │   │    DANCE_SONG      │   │      LINK       │
├──────────────────┤   ├────────────────────┤   ├─────────────────┤
│ • name           │   │ • dance_id (FK)    │   │ • kind          │
│ • country        │   │ • song_id (FK)     │   │   (YOUTUBE_TEACH│
│ • isGroup        │   │ • role (PRIMARY/   │   │    YOUTUBE_DANCE│
│ • listingStatus  │   │    ALTERNATIVE)    │   │    YOUTUBE_MUSIC│
└──────────────────┘   └─────────┬──────────┘   │ • url           │
                                 │              │ • dance_id (FK) │
                                 ▼              │ • videoId       │
                        ┌─────────────────┐    └─────────────────┘
                        │      SONG       │
                        ├─────────────────┤
                        │ • title         │
                        │ • artist        │
                        │ • year          │
                        │ • album         │
                        │ • bpm           │
                        │ • spotifyId     │
                        │ • albumArtUrl   │
                        └─────────────────┘
                                │
       ┌────────────────────────┘
       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         LINE_DANCE_SPEC                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│ • sourceText (TEXT)           ← Stepsheet original (manual o validat)      │
│ • importedStepsheet (TEXT)    ← Bloc de text importat de YouTube           │
│                                  (catàleg de components + seqüència)       │
│ • status                      ← DRAFT / PUBLISHED / VERIFIED               │
│ • notes                       ← Notes addicionals                          │
└─────────────────────────────────────────────────────────────────────────────┘

10. Consideracions Importants

Múltiples coreògrafs

Si un ball té més d'un coreògraf, separa'ls amb | al camp:

choreographer_name: Magali Chabret|John Smith
choreographer_country: FR|US

Múltiples vídeos per ball

Un ball pot tenir varis vídeos (teach, demo, música). Fes una fila per vídeo amb el mateix dance_name.

Control de duplicats

El sistema d'importació ha de:

Cercar ball per dance_name + choreographer_name + song_title/artist
Si existeix, afegir el link; si no, crear-lo tot

Camps opcionals buits

Deixa'ls buits (no null ni N/A), el parser ho gestionarà

Cançons via iTunes

El sistema cercarà la cançó a iTunes API amb song_title + song_artist per:

Evitar duplicats
Obtenir metadades addicionals (album, artwork, etc.)

11. Nom del Fitxer de Sortida

Format recomanat:

youtube_import_YYYYMMDD_HHMMSS.tsv

Exemple:

youtube_import_20260131_143022.tsv

Documents relacionats

Sistema d'Importació - Arquitectura general del pipeline d'importació
Redisseny Base de Dades - Model de dades complet

1. Introducció​

Separador Recomanat​

2. Camps del Fitxer TSV/CSV​

📹 Identificadors YouTube (per embebuts, imatges, etc.)​

💃 Dades del Ball (extretes del títol/descripció)​

👤 Coreògraf​

🎵 Cançó (per buscar a iTunes API)​

🔗 Tipus de Vídeo​

📝 Especificació (bloc de text lliure)​

3. Header del Fitxer TSV​

4. Exemple de Fila TSV​

5. Exemples de imported_stepsheet​

6. Recursos YouTube per al Software​

7. Flux de Treball per l'Agent Extern​

8. Mapeig TSV → Base de Dades​

9. Model de Dades de Referència​

10. Consideracions Importants​

Múltiples coreògrafs​

Múltiples vídeos per ball​

Control de duplicats​

Camps opcionals buits​

Cançons via iTunes​

11. Nom del Fitxer de Sortida​

Documents relacionats​