{"id":10301,"library":"torchfcpe","title":"TorchFCPE: Fast Context-based Pitch Estimation","description":"The official Pytorch implementation of Fast Context-based Pitch Estimation (FCPE), `torchfcpe` provides a robust and efficient solution for extracting fundamental frequency (F0) from audio signals. It is currently at version `0.0.4` and sees occasional updates, primarily focusing on model improvements and compatibility.","status":"active","version":"0.0.4","language":"en","source_language":"en","source_url":"https://github.com/CNChTu/FCPE","tags":["audio","pytorch","pitch estimation","deep learning","speech processing"],"install":[{"cmd":"pip install torchfcpe","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core PyTorch dependency for tensor operations and deep learning models (>=1.12.0)","package":"torch"},{"reason":"Required for audio loading, processing, and resampling (>=0.12.0)","package":"torchaudio"},{"reason":"Fundamental package for numerical operations","package":"numpy"},{"reason":"Utilities for audio analysis","package":"librosa"}],"imports":[{"symbol":"FCPE","correct":"from torchfcpe import FCPE"}],"quickstart":{"code":"import torch\nimport torchaudio\nfrom torchfcpe import FCPE\nimport os\n\n# --- Configuration ---\nsampling_rate = 44100 # Default sample rate for FCPE\nhop_length = 512    # Default hop length\ndevice = os.environ.get('FCPE_DEVICE', 'cuda' if torch.cuda.is_available() else 'cpu')\n\nprint(f\"Using device: {device}\")\n\n# --- 1. Initialize the FCPE model ---\nmodel = FCPE(\n    sampling_rate=sampling_rate,\n    hop_length=hop_length,\n    device=device\n)\n\n# --- 2. Create dummy audio data (or load real audio) ---\n# For a real scenario, replace with torchaudio.load('your_audio.wav')\n# This creates a 5-second mono sine wave at 440 Hz\nnum_samples = sampling_rate * 5 # 5 seconds of audio\nt = torch.linspace(0, 5, num_samples, device=device)\nfrequency = 440.0 # Hz\n# Generate a simple sine wave. FCPE expects mono audio.\n# Shape: (batch_size, num_samples)\naudio = torch.sin(2 * torch.pi * frequency * t).unsqueeze(0)\n\n# --- 3. Preprocess audio for the model ---\n# Ensure audio is on the correct device (already done for dummy data)\n# Ensure audio is 2D (batch_size, num_samples)\nif audio.dim() == 1:\n    audio = audio.unsqueeze(0)\n# If audio were stereo (e.g., shape (2, N)), convert to mono:\nif audio.shape[0] > 1: # Assuming batch_size is 1, check channel dim\n    audio = torch.mean(audio, dim=0, keepdim=True)\n\nprint(f\"Input audio shape: {audio.shape}\")\n\n# --- 4. Perform pitch estimation ---\nwith torch.no_grad():\n    f0, uv = model(audio)\n\n# f0: fundamental frequency (Hz), uv: unvoiced/voiced decision (boolean-like)\nprint(f\"Estimated F0 shape: {f0.shape}\")\nprint(f\"Estimated UV shape: {uv.shape}\")\nprint(f\"First 10 F0 values: {f0[0, :10].cpu().numpy()}\")\nprint(f\"First 10 UV values: {uv[0, :10].cpu().numpy()}\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `FCPE` model, prepare dummy audio data, and perform pitch estimation. It includes essential preprocessing steps like ensuring the correct device and input tensor shape. For real-world usage, replace the dummy audio with `torchaudio.load`."},"warnings":[{"fix":"Review custom `torchfcpe` subclasses or direct attribute access to ensure compatibility with standard `torch.nn.Module` methods and properties.","message":"Starting from `v0.0.4`, all FCPE models now correctly inherit directly from `torch.nn.Module`. While direct instantiation of `FCPE(...)` is generally stable, any custom subclasses or code directly manipulating internal model structure that relied on a previous inheritance hierarchy might require review.","severity":"breaking","affected_versions":">=0.0.4"},{"fix":"Ensure you are running `torchfcpe>=0.0.2` for the best device compatibility. If issues persist, explicitly set the `device` parameter during model initialization (e.g., `device='cpu'` or `device='mps'`).","message":"Improved device detection and specific support for Apple Silicon's MPS device were added in `v0.0.2`. Users upgrading from `v0.0.1` or experiencing device-related issues (especially with MPS) may find more reliable behavior in newer versions.","severity":"gotcha","affected_versions":"<0.0.2"},{"fix":"Always resample your input audio to `model.sampling_rate` using `torchaudio.transforms.Resample` before passing it to the model, or initialize the model with the sample rate of your audio.","message":"The `sampling_rate` parameter passed to the `FCPE` model during initialization must match the sample rate of your input audio. A mismatch will lead to incorrect pitch estimation or errors due to internal feature extraction assumptions.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install torchfcpe`","cause":"The `torchfcpe` library is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'torchfcpe'"},{"fix":"Move your input audio tensor to the same device as the model: `audio = audio.to(model.device)`","cause":"The input audio tensor is on a different device (e.g., CPU) than the `FCPE` model (e.g., CUDA or MPS).","error":"RuntimeError: Input type (torch.FloatTensor) and weight type (torch.cuda.FloatTensor) do not match"},{"fix":"Ensure your audio tensor has the correct shape. If 1D: `audio = audio.unsqueeze(0)`. If stereo (e.g., `(2, num_samples)`), convert to mono: `audio = torch.mean(audio, dim=0, keepdim=True)`.","cause":"The `FCPE` model expects a 2D input tensor of shape `(batch_size, num_samples)`. Your input might be 1D (mono, no batch dim) or 3D (e.g., batch, channels, samples).","error":"ValueError: expected 2D input (got N-D input)"},{"fix":"Use `model.device` to query the device the model is on. Ensure your `torchfcpe` library is up-to-date and installed from the official PyPI or GitHub source.","cause":"This error is likely from an older, potentially unofficial or modified version of FCPE, or a misunderstanding of how `torchfcpe` handles devices. The official `torchfcpe` model uses `model.device` directly.","error":"AttributeError: 'FCPE' object has no attribute 'get_device'"}]}