Fix docs review: ffmpeg guard, cleanup env, GPU column (#481)

* Fix docs review: ffmpeg guard, remove environment, GPU column

- video/input_output.py: proper ffmpeg guard with _FFMPEG_AVAILABLE
  flag and ModuleNotFoundError (was silently None)
- docs-preview.yaml: remove deployment environment (needs manual
  approval), use PR comment with create-or-update-comment instead
- tutorials/README.md: GPU column corrected for transcription and
  speech representations tutorials

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Restore deployment environment for docs preview

Use a single 'docs-preview' environment (pre-created via API with no
protection rules) instead of per-PR environments. The single
environment only needs to exist once and all PRs reuse it with
different URLs. Removed PR comment approach — the deployment URL
shows in the checks UI as "View deployment".

Also removed cleanup comment posting — the deployment status in
the checks UI handles this naturally.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Revert ffmpeg-python from video extras, improve error message

ffmpeg-python is a CLI wrapper (separate from torchcodec's shared
libs). It's not a core video dependency — keep it as an optional
install with a clear error message pointing to both the Python
package and system FFmpeg requirement.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Replace ffmpeg-python CLI with PyAV for video audio extraction

extract_audios_from_local_videos now uses av (PyAV), which is
already a video dependency, instead of ffmpeg-python (CLI wrapper).
PyAV wraps FFmpeg shared libraries directly — no CLI binary needed.

Eliminates the ffmpeg-python dependency entirely.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: satra

.github/workflows/docs-preview.yaml

@@ -14,7 +14,7 @@ jobs:
     if: github.event.action != 'closed'
     runs-on: ubuntu-latest
     environment:
-      name: docs-preview-pr-${{ github.event.pull_request.number }}
+      name: docs-preview
       url: https://sensein.group/senselab/pr-${{ github.event.pull_request.number }}/
     steps:
     - uses: actions/checkout@v5
@@ -60,8 +60,3 @@ jobs:
           git commit -m "Remove docs preview for PR #${PR_NUM}"
           git push origin docs
         fi
-    - name: Delete environment
-      uses: strumwolf/delete-deployment-environment@v3
-      with:
-        token: ${{ secrets.GITHUB_TOKEN }}
-        environment: docs-preview-pr-${{ github.event.pull_request.number }}

src/senselab/video/tasks/input_output.py

@@ -5,12 +5,10 @@
 from pathlib import Path
 from typing import Any, Dict, List, Union
 
-try:
-    import ffmpeg
-except ImportError:
-    ffmpeg = None  # type: ignore[assignment]
+import av
+import numpy as np
+import soundfile as sf
 
-# import shutil
 from senselab.utils.data_structures import from_strings_to_files, get_common_directory
 from senselab.utils.tasks.input_output import read_files_from_disk
 
@@ -20,40 +18,63 @@ def extract_audios_from_local_videos(
     audio_format: str = "wav",
     acodec: str = "pcm_s16le",
 ) -> Dict[str, Any]:
-    """Read files from disk and create a Hugging Face `Dataset` object."""
+    """Extract audio tracks from video files and return as a dataset.
 
-    def _extract_audio_from_local_video(video_path: Path, output_audio_path: str, format: str, acodec: str) -> None:
-        """Extract audio from a video file."""
-        try:
-            # Input stream configuration
-            input_stream = ffmpeg.input(video_path)
+    Uses PyAV (av) to decode the audio stream from each video file,
+    then writes the raw audio to disk in the requested format.
 
-            # Audio extraction configuration
-            audio_stream = input_stream.audio.output(output_audio_path, format=format, acodec=acodec)
+    Args:
+        files: Path(s) to video files.
+        audio_format: Output audio format (default: wav).
+        acodec: Audio codec hint (default: pcm_s16le). Used to select
+            output sample format (16-bit signed int for pcm_s16le).
 
-            # Execute ffmpeg command
-            ffmpeg.run(audio_stream, overwrite_output=True)
+    Returns:
+        A dataset dict of the extracted audio files.
+    """
 
-        except ffmpeg.Error as e:
-            print("An error occurred while extracting audio:", str(e))
+    def _extract_audio_from_local_video(video_path: Path, output_audio_path: str, fmt: str, codec: str) -> None:
+        """Extract audio from a video file using PyAV."""
+        container = av.open(str(video_path))
+        audio_stream = container.streams.audio[0]
+        sample_rate = audio_stream.rate or 16000
+
+        frames = []
+        for frame in container.decode(audio=0):
+            arr = frame.to_ndarray()
+            if arr.ndim > 1:
+                arr = arr.mean(axis=0)  # downmix to mono
+            frames.append(arr)
+        container.close()
+
+        if not frames:
+            return
+
+        audio_data = np.concatenate(frames)
+
+        # Match codec hint to sample format
+        if "s16" in codec:
+            audio_data = (
+                (audio_data * 32767).clip(-32768, 32767).astype(np.int16)
+                if audio_data.dtype != np.int16
+                else audio_data
+            )
+
+        sf.write(output_audio_path, audio_data, sample_rate, format=fmt.upper())
 
     if isinstance(files, str):
         files = [files]
     formatted_files = from_strings_to_files(files)
     common_path = get_common_directory(files)
 
-    # Create a temporary directory to hold the audio files
     temp_dir = tempfile.mkdtemp()
 
     audio_files_paths = []
     for file in formatted_files:
         base_file_name = os.path.splitext(str(file.filepath).replace(common_path, ""))[0]
         output_audio_path = os.path.join(temp_dir, f"{base_file_name}.{audio_format}")
-        _extract_audio_from_local_video(file.filepath, output_audio_path, format=audio_format, acodec=acodec)
+        os.makedirs(os.path.dirname(output_audio_path), exist_ok=True)
+        _extract_audio_from_local_video(file.filepath, output_audio_path, fmt=audio_format, codec=acodec)
         audio_files_paths.append(output_audio_path)
 
-    audio_dataset = read_files_from_disk(audio_files_paths)
-
-    # Clean up the temporary non empty directory
-    # shutil.rmtree(temp_dir)
-    return audio_dataset
+    return read_files_from_disk(audio_files_paths)

tutorials/README.md

@@ -76,8 +76,8 @@ if not GPU_AVAILABLE:
 | voice_activity_detection | Optional | Yes* | Detect speech segments |
 | voice_cloning | Yes | No | Voice conversion |
 | audio_recording_and_acoustic_analysis | No | No | Recording and acoustic feature analysis |
-| transcription_and_phonemic_analysis | No | No | Transcription and phoneme-level analysis |
-| speech_representations_lab | Optional | No | Speech representation learning |
+| transcription_and_phonemic_analysis | Yes | No | Transcription and phoneme-level analysis |
+| speech_representations_lab | Yes | No | Acoustic vs articulatory speech representations |
 
 *Requires accepting pyannote model terms on HuggingFace