# Soundscape Recording Search

> Find real, freely licensed sound recordings by place, category and keywords. Searches Wikimedia Commons for geotagged audio recordings — birdsong, rain, rivers, streets, machines, voices and field recordings — by region, map point, sound category and keywords. Every result carries its licence, author, attribution line, coordinates and links to the source page and file; only CC0, public-domain, CC BY and CC BY-SA recordings are listed unless you ask for the others.

Part of usefulweb.app (https://usefulweb.app/). Part of [Soundscape Atlas](https://soundscape.usefulweb.app/) (ownerApp: soundscape). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://soundscaperecordingsearch.usefulweb.app/ (interactive tool at https://soundscaperecordingsearch.usefulweb.app/tool)
- JSON API: POST https://soundscaperecordingsearch.usefulweb.app/api/v1/calculate with a JSON object of inputs (schema: https://soundscaperecordingsearch.usefulweb.app/api/v1/tool)
- OpenAPI: https://soundscaperecordingsearch.usefulweb.app/openapi.json
- MCP (Streamable HTTP): https://soundscaperecordingsearch.usefulweb.app/mcp - tool `soundscape_recording_search`

## Inputs
- query (text): Search words - Optional plain words such as “rain forest” or “harbour”. Search operators are ignored.
- category (select): Sound category
- region (select): Region - “Whole world” lists only recordings with coordinates.
- lat (number): Latitude (for “Around a point”)
- lon (number): Longitude (for “Around a point”)
- radiusKm (number): Radius (for “Around a point”)
- limit (number): Results per page
- offset (number): Skip the first results - Use the “next offset” of a previous search to get the next page.
- includeRestricted (boolean): Also list recordings that cannot be remixed - They are marked and never usable in Soundscape Atlas scenes.

## Method
- Builds a Wikimedia Commons search (CirrusSearch) for audio files: `filetype:audio`, a `nearcoord:` circle for the region or point, an OR-group of keywords for the category and your own words.
- Asks the MediaWiki API for each file’s coordinates, file URL, MIME type, duration, Wikimedia’s MP3 transcode and the licence, author, credit, date, description and categories from the file page (extmetadata). Nothing is filled in or guessed.
- Classifies the licence conservatively: only CC0, public domain, CC BY and CC BY-SA count as usable; NonCommercial, NoDerivatives, GFDL-only, Free Art and unknown licences are not usable for remixing.
- Writes a TASL attribution line (title, author, licence with link, source) for every recording, and tags results with sound categories by keywords in the title, description and categories.
- Caches region and world searches for 12 hours to keep the load on Wikimedia low; searches around a point are never cached, so no coordinates are kept on the server.

## Limits
- Licence and author data come from the Commons file pages and can be incomplete or wrong; check the file page before publishing. Sound tags are a keyword guess. Recordings can be removed from Commons at any time.