{"record":{"id":"ca1fa65a5bbc47e9","repo":"unslothai/unsloth","slug":"whisper-dataset-needs-audio-and-text-columns","errorCode":null,"errorMessage":"Whisper dataset needs 'audio' and 'text' columns, got: {dataset.column_names}","messagePattern":"Whisper dataset needs 'audio' and 'text' columns, got: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/training/trainer.py","lineNumber":2435,"sourceCode":"        dataset,\n        eval_split = None,\n        custom_format_mapping = None,\n    ):\n        \"\"\"Preprocess dataset for Whisper speech-to-text training.\n\n        Mirrors Whisper.ipynb: extract audio features with Whisper's feature\n        extractor, tokenize text labels. Returns (train_data, eval_data),\n        each a list of dicts with 'input_features' and 'labels'.\n        \"\"\"\n        from datasets import Audio\n\n        WHISPER_SAMPLE_RATE = 16000\n\n        resolved = self._resolve_audio_columns(dataset, custom_format_mapping)\n        audio_col = resolved[\"audio_col\"]\n        text_col = resolved[\"text_col\"]\n        if not audio_col or not text_col:\n            raise ValueError(\n                f\"Whisper dataset needs 'audio' and 'text' columns, got: {dataset.column_names}\"\n            )\n\n        # Cast audio to 16kHz (Whisper's expected sample rate)\n        dataset = dataset.cast_column(audio_col, Audio(sampling_rate = WHISPER_SAMPLE_RATE))\n\n        # Train/eval split (notebook does dataset.train_test_split)\n        eval_dataset_raw = None\n        if eval_split:\n            splits = dataset.train_test_split(test_size = 0.06, seed = 42)\n            dataset = splits[\"train\"]\n            eval_dataset_raw = splits[\"test\"]\n\n        self._update_progress(status_message = \"Processing audio for Whisper...\")\n        logger.info(\n            f\"Whisper preprocessing: audio_col='{audio_col}', text_col='{text_col}', \"\n            f\"samples={len(dataset)}\\n\"\n        )","sourceCodeStart":2417,"sourceCodeEnd":2453,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/training/trainer.py#L2417-L2453","documentation":"ValueError raised at the start of Whisper fine-tune preprocessing when column resolution cannot find both an audio and a text column. Whisper training extracts log-mel input_features from 16kHz audio and tokenizes the text as labels, so both columns are required before train/test splitting and feature extraction begin.","triggerScenarios":"Whisper fine-tune with a dataset that has audio but transcripts under an unrecognized column name (or no transcript column at all), or vice versa; custom_format_mapping not supplied for unconventional names.","commonSituations":"Common ASR datasets using 'sentence' (Common Voice style) or 'transcript' without mapping; CSV imports with generic headers; wrong trainer path chosen for a non-audio task.","solutions":["Map the transcript column: custom_format_mapping={'sentence': 'text'} (audio usually resolves by Audio type).","Rename columns so 'audio' and 'text' are both present.","Verify the dataset genuinely has aligned audio+transcript pairs for ASR training."],"exampleFix":"// before\ndataset  # columns: ['audio', 'sentence']  (Common Voice style)\n// after\ndataset = dataset.rename_column('sentence', 'text')","handlingStrategy":"validation","validationCode":"def whisper_ready(dataset) -> bool:\n    return 'audio' in dataset.column_names and 'text' in dataset.column_names\n\nassert whisper_ready(dataset), \"Whisper needs 'audio' and 'text' columns\"","typeGuard":"def is_asr_dataset(dataset) -> bool:\n    return 'audio' in dataset.column_names and 'text' in dataset.column_names","tryCatchPattern":"try:\n    train_data, eval_data = trainer._preprocess_whisper_dataset(dataset, mapping, eval_split=True)\nexcept ValueError as e:\n    if \"Whisper dataset needs\" in str(e):\n        dataset = dataset.rename_column('sentence', 'text')  # Common Voice style\n        train_data, eval_data = trainer._preprocess_whisper_dataset(dataset, mapping, eval_split=True)","preventionTips":["Rename transcript columns like 'sentence'/'transcript' to 'text' at load time.","Cast the audio column with datasets.Audio(sampling_rate=16000) during preparation.","Run schema validation before starting a Whisper run to avoid wasting setup time."],"tags":["audio","whisper","asr","dataset","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}