# Freesound Scraper (`crawlerbros/freesound-scraper`) Actor

Scrape Freesound.org - a community-driven library of 600,000+ Creative Commons-licensed sound effects and samples. Search by keyword, tag, or uploader; get title, license, duration, downloads, rating, tags, and preview audio URLs.

- **URL**: https://apify.com/crawlerbros/freesound-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** Automation, Developer tools, Integrations
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Freesound Scraper

Scrape **Freesound.org** — a community-driven library of 600,000+ Creative Commons-licensed sound effects and samples. Search by keyword, browse by tag, or browse by uploader, with license/format/duration/rating filters. Reads Freesound's fully public, server-rendered search-results pages. No login, no API key, no proxy required.

### What this actor does

- **Four modes:** `search` (keyword), `byTag` (browse a tag), `byUser` (browse an uploader), `similarTo` (Freesound's own "sounds like this one" recommendations for a given sound ID)
- **License filter** — Creative Commons 0, Attribution, Attribution NonCommercial, Sampling+
- **File-format filter** — WAV, MP3, AIFF, FLAC, OGG, M4A
- **Duration range** — min/max seconds
- **Sort** — relevance, duration, date added, downloads (matches Freesound's own sort dropdown)
- **Client-side filters** — minimum rating, minimum downloads
- **Preview audio** — MP3 and OGG preview URLs for every sound, plus waveform/spectrum images
- **Empty fields are omitted** — you only ever see fields that were actually found for a sound

### Output per sound

- `soundId` — Freesound sound ID
- `title`
- `uploader`, `uploaderId`
- `description`
- `tags[]`
- `duration` — seconds (float)
- `sampleRate` — Hz
- `license` — one of Freesound's 4 Creative Commons license labels
- `numDownloads`, `numComments`
- `rating`, `ratingCount` — average star rating (0-5) and number of ratings (omitted when the sound has no ratings yet)
- `packName`, `packUrl` — parent sound pack, when the sound belongs to one
- `uploadDate` — ISO date the sound was added
- `previewMp3Url`, `previewOggUrl` — streamable preview audio (Freesound's own CDN)
- `waveformImageUrl`, `spectrumImageUrl` — visualization images
- `sourceUrl` — canonical Freesound sound page URL
- `searchQuery`, `searchTags[]`, `searchUsername` — the search parameters used for this run (`search`/`byTag`/`byUser` modes)
- `similarToSoundId` — the input `soundId` this record was recommended as similar to (`similarTo` mode only)
- `recordType: "sound"`, `scrapedAt`

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string (select) | `search` | `search` / `byTag` / `byUser` / `similarTo` |
| `searchQuery` | string | `piano` | Keyword search (mode=search) |
| `tags` | array | – | Tags to filter/browse by (AND'ed together) |
| `username` | string | – | Uploader username (mode=byUser, or extra filter) |
| `soundId` | string | – | Freesound sound ID to find similar sounds for (mode=similarTo) |
| `license` | string (select) | `any` | Creative Commons license filter |
| `fileType` | string (select) | `any` | Audio file format filter |
| `minDuration` / `maxDuration` | integer | – | Duration range in seconds |
| `sortBy` | string (select) | `relevance` | Sort order |
| `minRating` | integer | `0` | Minimum star rating 0-5 (client-side) |
| `minDownloads` | integer | `0` | Minimum download count (client-side) |
| `onlyGeotagged` | boolean | `false` | Only geotagged sounds |
| `groupByPack` | boolean | `true` | Collapse multi-sound packs to one representative result |
| `fetchFileDetails` | boolean | `false` | Also open each sound page for file size/bitrate/bit depth/channels (slower) |
| `maxItems` | int | `50` | Hard cap on returned records (1-1000) |

#### Example: search for rain sounds, CC0 only, WAV format

```json
{
  "mode": "search",
  "searchQuery": "rain",
  "license": "creativeCommons0",
  "fileType": "wav",
  "maxItems": 50
}
```

#### Example: browse the "footsteps" tag, longest first

```json
{
  "mode": "byTag",
  "tags": ["footsteps"],
  "sortBy": "durationDesc",
  "maxItems": 30
}
```

#### Example: all sounds by a specific uploader

```json
{
  "mode": "byUser",
  "username": "InspectorJ",
  "maxItems": 100
}
```

#### Example: sounds similar to a specific sound

```json
{
  "mode": "similarTo",
  "soundId": "468996",
  "maxItems": 20
}
```

#### Example: short, highly-downloaded attribution-licensed loops

```json
{
  "mode": "search",
  "searchQuery": "loop",
  "license": "attribution",
  "maxDuration": 10,
  "minDownloads": 500,
  "sortBy": "downloadsDesc"
}
```

### Use cases

- **Game/app audio libraries** — bulk-collect CC-licensed sound effects by category for a project asset pipeline
- **Music production** — find CC0/Attribution samples and loops filtered by BPM tags and duration
- **Podcast/video production** — source royalty-free ambience, foley, and transition sounds
- **License auditing** — verify which license a batch of previously-downloaded Freesound samples carries
- **Dataset building** — collect labeled audio samples with tags/metadata for ML training sets

### Limitations

- **No login-gated fields.** Freesound's search-results pages show everything needed for discovery (title, tags, license, duration, downloads, rating, preview audio) without an account. Fields only visible on a logged-in user's own dashboard (comments text, download history) are out of scope.
- **`minRating`/`minDownloads` are applied client-side.** Freesound's search UI has no server-side rating/downloads-threshold filter, so these are applied across the batch of records this run actually fetched, not the entire result set — a low `maxItems` combined with a strict `minRating`/`minDownloads` may return fewer records than expected.
- **`byTag`/`byUser` browsing defaults to newest-first** when no `searchQuery` is given (matching Freesound's own behavior when you click a tag or username link), since "relevance" sorting is only meaningful with a keyword.
- **`similarTo` mode returns Freesound's own fixed recommendation list** for a sound (typically under a dozen results, ordered by Freesound's own similarity ranking — `sortBy` doesn't apply). `license`/duration filters are applied client-side against that list; `tags` are not shown on similar-sounds cards so `tags` filtering/output isn't available in this mode.

### FAQ

**What's Freesound?** A collaborative database of Creative Commons-licensed sounds, run by the Music Technology Group at Universitat Pompeu Fabra. See [freesound.org](https://freesound.org).

**Is this affiliated with Freesound?** No. This is an independent, third-party actor that reads Freesound's publicly accessible search pages.

**Can I download the full-quality original audio file?** This actor returns the streamable MP3/OGG *preview* URLs (same audio Freesound's own player uses), not the original uploaded file. Downloading originals requires a Freesound account and API key, which is outside this actor's no-login scope.

**Why do some sounds have no `rating`/`ratingCount`?** Freesound only shows a rating once a sound has received at least one vote. Sounds with zero ratings simply omit those fields.

**What does `groupByPack` do?** When many similar sounds belong to the same upload pack (e.g. 50 individual piano notes), Freesound's default search view collapses them to a single representative result with a link to "see N more from this pack." Turn `groupByPack` off to see every individual sound in the pack.

**Does this actor need a proxy or login?** No — Freesound's search pages are served without any anti-bot challenge, so this actor runs entirely on Apify's free plan with no proxy and no credentials by default (it will only escalate to Apify's free AUTO proxy if it ever hits an unexpected rate limit).

**How many results does Freesound have in total?** 600,000+ sounds and growing; a broad query like "piano" alone matches 19,000+ results.

# Actor input Schema

## `mode` (type: `string`):

What to fetch: keyword search, browse all sounds under a tag, or browse all sounds by an uploader.

## `searchQuery` (type: `string`):

Keyword(s) to search for, e.g. 'piano', 'rain', 'footsteps', 'explosion'. Can be combined with Tags/Uploader below to narrow a search further.

## `tags` (type: `array`):

One or more Freesound tags. All listed tags must be present on a sound (AND). Examples: 'piano', 'loop', 'ambient', 'field-recording', 'drums', '120bpm'.

## `username` (type: `string`):

Exact Freesound username to browse/filter by, e.g. 'InspectorJ' or 'unfa'. Case-sensitive, must match the uploader's profile URL slug.

## `soundId` (type: `string`):

Numeric Freesound sound ID to find similar sounds for, e.g. '468996' (from a sound page URL like freesound.org/people/<user>/sounds/468996/). Uses Freesound's own 'Find similar sounds' recommender.

## `license` (type: `string`):

Only return sounds under this Creative Commons license.

## `fileType` (type: `string`):

Only return sounds uploaded in this audio file format.

## `minDuration` (type: `integer`):

Only return sounds at least this many seconds long. Leave empty for no minimum.

## `maxDuration` (type: `integer`):

Only return sounds at most this many seconds long. Leave empty for no maximum.

## `sortBy` (type: `string`):

How Freesound orders the results. 'Relevance' requires a search query to be meaningful; browsing by tag/uploader with no query defaults to newest-first automatically.

## `minRating` (type: `integer`):

Only return sounds rated at least this many stars (0-5). Applied client-side; unrated sounds are excluded once this is set above 0. 0 means no minimum.

## `minDownloads` (type: `integer`):

Only return sounds with at least this many downloads. Applied client-side. 0 means no minimum.

## `onlyGeotagged` (type: `boolean`):

Only return sounds that have geolocation information attached.

## `groupByPack` (type: `boolean`):

When multiple results belong to the same sound pack, Freesound collapses them to one representative result (Freesound's own default behaviour). Turn off to see every individual sound.

## `fetchFileDetails` (type: `boolean`):

For each result, additionally open its Freesound sound page to capture file size, bitrate (lossy formats) or bit depth (lossless formats), and channel count (Mono/Stereo) -- none of these are available on the search-results page. Adds one extra request per sound, so runs take noticeably longer.

## `maxItems` (type: `integer`):

Hard cap on the number of sound records to return.

## Actor input object example

```json
{
  "mode": "search",
  "searchQuery": "piano",
  "tags": [],
  "license": "any",
  "fileType": "any",
  "sortBy": "relevance",
  "minRating": 0,
  "minDownloads": 0,
  "onlyGeotagged": false,
  "groupByPack": true,
  "fetchFileDetails": false,
  "maxItems": 50
}
```

# Actor output Schema

## `sounds` (type: `string`):

Dataset containing all scraped Freesound sound records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "search",
    "searchQuery": "piano",
    "tags": [],
    "license": "any",
    "fileType": "any",
    "sortBy": "relevance",
    "minRating": 0,
    "minDownloads": 0,
    "onlyGeotagged": false,
    "groupByPack": true,
    "fetchFileDetails": false,
    "maxItems": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/freesound-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "search",
    "searchQuery": "piano",
    "tags": [],
    "license": "any",
    "fileType": "any",
    "sortBy": "relevance",
    "minRating": 0,
    "minDownloads": 0,
    "onlyGeotagged": False,
    "groupByPack": True,
    "fetchFileDetails": False,
    "maxItems": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/freesound-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "search",
  "searchQuery": "piano",
  "tags": [],
  "license": "any",
  "fileType": "any",
  "sortBy": "relevance",
  "minRating": 0,
  "minDownloads": 0,
  "onlyGeotagged": false,
  "groupByPack": true,
  "fetchFileDetails": false,
  "maxItems": 50
}' |
apify call crawlerbros/freesound-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=crawlerbros/freesound-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/IYVoJh5ZuKsTWenEM/builds/hjma4L0kf2M5dOk4A/openapi.json