sciss / scalafreesound

Freesound database queries and downloads for Scala. Mirror of

Version Matrix


Build Status Maven Central Donate using Liberapay


ScalaFreesound is a library to query the Freesound audio database. It is (C)opyright 2010–2020 by Hanns Holger Rutz. All rights reserved. It is released under the GNU Affero General Public License and comes with absolutely no warranties. To contact the author, send an e-mail to

Please consider supporting this project through Liberapay (see badge above) – thank you!

requirements / installation

This project builds with sbt against Scala 2.12, 2.13, Dotty. The last version to support Scala 2.11 was 1.19.0.

To link to it:

libraryDependencies += "de.sciss" %% "scalafreesound"  % v

The current version v is "2.4.0"

Or to link to an individual module

libraryDependencies += "de.sciss" %% "scalafreesound-core"        % v
libraryDependencies += "de.sciss" %% "scalafreesound-swing"       % v
libraryDependencies += "de.sciss" %% "scalafreesound-lucre"       % v
libraryDependencies += "de.sciss" %% "scalafreesound-views"       % v
libraryDependencies += "de.sciss" %% "scalafreesound-compression" % v
  • the core module provides functions for searching the database and downloading previews and files.
  • the swing module provides user interface elements for searching and viewing results.
  • the lucre module provides a bridge to SoundProcesses/.
  • the views module provides a bridge to Mellite.
  • the compression module provides decoders from FLAC, Ogg, and mp3 to PCM.


Please see the file


The easiest to play around is to run sbt test:console which will import useful symbols and also load the files client.json and access_token if found. An implicit Client is required for searches, and an implicit AccessToken is required for downloading sounds.

import de.sciss.freesound._
import Implicits._

If you have never used Freesound, you must first create an account. Then you need to generate an API key. Go to and follow the link to Once you have created a key, create a file client.json with the following content:

  "id"    : "<client-id>",
  "secret": "<client-secret>"

With the bits copied from the Client id and Client secret/Api key sections into these two entries. The client keys identify the application that is running queries against the Freesound database, for operations that can be performed without identifying as a particular user. If you don't want to restart the sbt console to automatically load those keys, simply define them as follows:

implicit val client = Client(id = "foo", secret = "bar") // your correct code here

Now you should be able to run a query

val fut = Freesound.textSearch("water", Filter(numChannels = 2, sampleRate = 44100, duration = 1.0 to *), sort = Sort.DurationShortest)

The search filter specifies that the sound must be stereophonic at 44.1 kHz sampling rate, and with a duration of at least one second. This returns a Future[Seq[Sound]], sorted by duration. So once that is finished, you can access the values:

fut.foreach { res => println(res.head) }

This will print something like

  fileName    = Knife Hit Pan Filled With Water 4.wav,
  tags        = List(impact, hit, metal, water, knife, struck, pong, pan),
  description = Recorded using a Zoom H4N.,
  userName    = riddzy,
  created     = 2014-04-23T17:38:19.079851,
  license     =,
  pack 	      = None,
  geoTag      = None,
  fileType    = Wave,
  duration    = 1.000,
  numChannels = 2,
  sampleRate  = 44100.0,
  bitDepth    = 16,
  bitRate     = 1387.0,
  fileSize    = 177492,
  numDownloads= 20,
  avgRating   = 0.0,
  numRatings  = 0,
  numComments = 0

Let's assume the future is completed, and we assign the first result for simplicity:

val sound = fut.value.get.get.head

The download URL would be this:



Next, we want to download that sound. For this we need an OAuth2 authentication based on our user account. You must open the following website: Where ######## is replaced by the Client id section of the api-key registration page. This will then give you a message like

Permission granted to application ScalaFreesound!.
Your authorization code:

We can then generate access keys using

val futAuth = Freesound.getAuth(<code>)

And write those keys to disk if we wish:

futAuth.foreach { implicit auth => Freesound.writeAuth() }

Now we're ready to download the sound file., new

We should then find the file Knife Hit Pan Filled With Water 4.wav on the disk.