# SunoGPT Metadata JSON Format

The metadata files are in JSONL format (one JSON object per line). Each record represents a single audio track.

## Core Required Fields

- `id`: Unique identifier for the track
  - Example: `"ntjYV1Pc7yk"`
- `local_filepath`: Local filesystem path to the audio file
  - Example: `"/app2/suno/data/raw_audio_opus_v0/ntjYV1Pc7yk.opus"`
- `s3_filepath`: S3 path to the audio file (optional if local_filepath is specified, used as backup)
  - Example: `"s3://webdataset/bundles/v0/discogs/audio/ntjYV1Pc7yk.opus"`
- `duration_s`: Duration of the track in seconds
  - Example: `174.29`
- `weight`: Sampling weight for training
  - Example: `1.0`

## Optional Content Fields

- `text`: Lyrics/text content of the track
  - Example: `"Who do you think is gonna be enough\nPick up the phone..."`
- `tags`: Array of genre/style/year tags
  - Example: `["Pop", "2023", "Electronic"]`
- `lang`: Language code
  - Example: `"en"`
- `audio_type`: String indicating the type of audio, "music", "speech" or "sfx"
  - Example: `"sfx"`

## Advanced Metadata Fields

- `text_aligned`: Array of timestamped lyrics
  - Example: `[[10.5, 15.2, "Chorus lyrics"]]`
- `hook_offset_s`: Time offset for hook/chorus section
  - Example: `32.5`
- `stems`: Object mapping stem types to file paths
  - Example: `{"Vocals": "/path/to/vocals.opus", "Drums": "/path/to/drums.opus"}`
- `artist_ids`: Array of artist identifiers for conditioning
  - Example: `["artist_123", "artist_456"]`
- `playlist_ids`: Array of playlist identifiers for conditioning
  - Example: `["playlist_abc", "playlist_def"]`
- `cover_ids`: Array of cover version identifiers
  - Example: `["cover_xyz"]`
- `overpaint_id`: ID for instrumental version (vocal separation)
  - Example: `"instrumental_789"`
- `underpaint_id`: ID for vocal-only version (instrumental separation)
  - Example: `"vocals_only_101"`
- `sample_source_id`: ID for source song to sample
  - Example: `"sample_source_123"`
- `remix_source_id`: ID for source song to remix
  - Example: `"remix_source_123"`
- `mashup_source_ids`: Array of IDs to mashup
  - Example: `["mashup_source_abc", "mashup_source_def"]`
`

## Audio Processing Fields

- `cutoff_freq`: High frequency cutoff for audio processing
  - Example: `16000`
- `start_s`, `end_s`: Track segment boundaries
  - Example: `0.5`, `174.0`
- `vocal_start_s`, `vocal_end_s`: Vocal timing boundaries
  - Example: `8.2`, `165.8`
- `original_duration_s`: Original track duration before processing
  - Example: `180.0`

## Extended Audio Features (v3 format)

Tags can include computed audio features:
- `quality: X`: Audio quality score
  - Example: `"quality: 17"`
- `spectral_centroid: X`: Frequency distribution metric
  - Example: `"spectral_centroid: -1.4"`
- `bass: X`, `mid: X`, `high: X`: Frequency band levels
  - Example: `"bass: 1.0"`, `"mid: -0.5"`, `"high: -0.6"`
- `stereo_width: X`: Stereo field width
  - Example: `"stereo_width: -0.6"`
- `spectral_flatness: X`: Tonal vs noise content
  - Example: `"spectral_flatness: -0.9"`
- `crest_factor: X`: Dynamic range measure
  - Example: `"crest_factor: -0.2"`
- `loudness: X`: Perceived loudness level
  - Example: `"loudness: 0.1"`

## Training Usage

These fields enable:
- **Text conditioning**: `text`, `tags`
- **Audio segmentation**: `duration_s`, `text_lines`, `hook_offset_s`
- **Multi-track conditioning**: `artist_ids`, `playlist_ids`, `cover_ids`
- **Stem separation**: `stems`, `overpaint_id`, `underpaint_id`
- **Audio quality control**: `cutoff_freq`, quality metrics
- **SFX generation**: `audio_type`