The freesound Reference Manual

This is the freesound Reference Manual, version 1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 16:27:10 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 freesound

A client for Freesound.org.

Author

Nuno Trocado https://nunotrocado.com

Home Page

https://nunotrocado.com/freesound/

Source Control

(GIT https://github.com/ntrocado/freesound)

License

MIT

Version

1.0

Dependencies
  • alexandria (system).
  • cl-ppcre (system).
  • dexador (system).
  • yason (system).
  • trivial-open-browser (system).
Source

freesound.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 freesound/freesound.asd

Source

freesound.asd.

Parent Component

freesound (system).

ASDF Systems

freesound.


3.1.2 freesound/package.lisp

Source

freesound.asd.

Parent Component

freesound (system).

Packages

freesound.


3.1.3 freesound/freesound.lisp

Dependency

package.lisp (file).

Source

freesound.asd.

Parent Component

freesound (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 freesound

Common Lisp client to the Freesound API.

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *client-id*

An alphanumeric string issued by Freesound, used as part of OAuth2 authentication.

Package

freesound.

Source

freesound.lisp.

Special Variable: *oauth2-access-token*

An alphanumeric string used as an access token for OAuth2 restricted resources. Call ‘oauth2-get-tokens‘ to initialize.

Package

freesound.

Source

freesound.lisp.

Special Variable: *oauth2-refresh-token*

An alphanumeric string used to get a new OAuth2 access token, without starting the whole authentication process. Call ‘oauth2-get-tokens‘ to initialize. To refresh the OAuth2 access token, pass this to ‘oauth2-get-tokens‘ with ‘:refresh t‘.

Package

freesound.

Source

freesound.lisp.

Special Variable: *token*

An alphanumeric string issued by Freesound to authenticate API calls.

Package

freesound.

Source

freesound.lisp.


5.1.2 Ordinary functions

Function: analysis (sound-id &key descriptors normalized)

Retrieve analysis information (content-based descriptors) on SOUND-ID.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id58

Package

freesound.

Source

freesound.lisp.

Function: bookmark (sound-id &key name category)

Bookmark an existing sound SOUND-ID. The sound will be bookmarked by the Freesound user logged in using OAuth2, therefore this method requires OAuth2 authentication.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id66

Package

freesound.

Source

freesound.lisp.

Function: combined-search (&key query filter sort target descriptors-filter page page-size fields descriptors normalized)

Perform a combination of text search and content search, returning a hash-table with the sound list response.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id55

See ‘text-search‘ and ‘content-search‘.

Package

freesound.

Source

freesound.lisp.

Function: comment (sound-id comment)

Post a COMMENT to an existing sound SOUND-ID. The comment will appear to be made by the Freesound user logged in using OAuth2.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id68

Package

freesound.

Source

freesound.lisp.

Function: comments (sound-id &key page page-size)

Retrieves comments for SOUND-ID.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id60

Package

freesound.

Source

freesound.lisp.

Function: content-search (target &key descriptors-filter page page-size fields descriptors normalized)

Search sounds based on their content descriptors, returning a hash-table with the sound list response.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id54

The filter syntax described in ‘text-search‘ also applies to DESCRIPTORS-FILTER.

Package

freesound.

Source

freesound.lisp.

Function: describe-sound (upload-filename tags description license &key name pack geotag)

Describe a previously uploaded audio file that has not yet been described. OAuth2 required.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id63

LICENSE is either one of the strings accepted by the API, or one of the following: :attribution, :attribution-noncommercial, :creative-commons.

Package

freesound.

Source

freesound.lisp.

Function: descriptors ()

Information about the available audio descriptors that are extracted from Freesound sounds.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id81

Package

freesound.

Source

freesound.lisp.

Function: download (sound-id pathname &key if-exists if-does-not-exist)

Download SOUND-ID into PATHNAME. Keyword options are as in ‘open‘. OAuth2 required.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id61

Package

freesound.

Source

freesound.lisp.

Function: edit-sound-description (sound-id &key name tags description license pack geotag)

Edit the description of an already existing sound. Note that this resource can only be used to edit descriptions of sounds created by the Freesound user logged in using OAuth2.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id65

LICENSE is either one of the strings accepted by the API, or one of the following: :attribution, :attribution-noncommercial, :creative-commons.

Package

freesound.

Source

freesound.lisp.

Function: info (sound-id &key fields descriptors normalized)

Retrieve information about SOUND-ID.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id57

Package

freesound.

Source

freesound.lisp.

Function: me ()

Information about the user that is logged in using the OAuth2 procedure.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id80

Package

freesound.

Source

freesound.lisp.

Function: oauth2-authorize (&optional client-id)

As the first step of OAuth2 authentication, open the default browser on a Freesound page, where users are prompted to log in and asked to give permission for the application. The url is also printed to standard output.

Package

freesound.

Source

freesound.lisp.

Function: pack-download (pack-id pathname &key if-exists if-does-not-exist)

Download PACK-ID into PATHNAME. Keyword options are as in ‘open‘. OAuth2 required.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id78

Package

freesound.

Source

freesound.lisp.

Function: pack-instance (pack-id)

Retrieve information about the pack PACK-ID.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id76

Package

freesound.

Source

freesound.lisp.

Function: pack-sounds (pack-id &key page page-size fields descriptors normalized)

Retrieve information about the sounds included in the pack PACK-ID.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id77

Package

freesound.

Source

freesound.lisp.

Function: pending-uploads ()

Retrieve a list of audio files uploaded by the Freesound user logged in using OAuth2 that have not yet been described, processed or moderated.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id64

Package

freesound.

Source

freesound.lisp.

Function: preview (sound-id pathname &key format)

Download a lossy version of SOUND-ID, writing it to PATHNAME. FORMAT is either :hq-mp3, :hq-ogg, :lq-mp3, :lq-ogg, where "hq" is higher quality and "lq" lower quality.

Package

freesound.

Source

freesound.lisp.

Function: print-info (info &optional stream)

Pretty print INFO, which is the response to ‘info‘ (sound instance) or to ‘analysis‘.

Package

freesound.

Source

freesound.lisp.

Function: print-search-result (search-result &optional stream)

Pretty print SEARCH-RESULT, a sound list response.

Package

freesound.

Source

freesound.lisp.

Function: rate (sound-id rating)

Rate an existing sound SOUND-ID with RATING, between 0 and 5 (where 5 is the maximum). The sound will be rated by the Freesound user logged in using OAuth2.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id67

Package

freesound.

Source

freesound.lisp.

Function: similar (sound-id &key descriptors-filter page page-size fields descriptors normalized)

Retrieve sounds similar to SOUND-ID, returning a hash table with the sound list response.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id59

The filter syntax described in ‘text-search‘ also applies to DESCRIPTORS-FILTER.

Package

freesound.

Source

freesound.lisp.

Function: text-search (query &key filter sort group-by-pack page page-size fields descriptors normalized)

Search sounds by matching their tags and other kids of metadata, returning a hash-table with the sound list response.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id53

FILTER is either a string conforming to the API syntax, or a list of key/value pairs. For example:
(text-search "trumpet" :filter ’((:type "ogg") (:channels 2)))

Each filter property can be further specified with the operators :and, :or, :range, :range-to, and :range-from. For example: (text-search "rain"
:filter ’((:tag (:and "soundscape" "forest"))
(:created (:range-from "2010-12-01T23:59:59.999Z"))
(:duration (:range 10 120))))

Package

freesound.

Source

freesound.lisp.

Function: upload (file &key name tags description license pack geotag)

Upload an audio FILE into Freesound and (optionally) describe it. If a description is intended, all of TAGS, DESCRIPTION and LICENSE are required. OAuth2 required.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id62

LICENSE is either one of the strings accepted by the API, or one of the following: :attribution, :attribution-noncommercial, :creative-commons.

Package

freesound.

Source

freesound.lisp.

Function: user-bookmark-categories (username &key page page-size)

Retrieve the bookmark categories uploaded by Freesound user USERNAME, returning a hash table with the sound list response.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id73

Package

freesound.

Source

freesound.lisp.

Function: user-packs (username &key page page-size)

Retrieve information about the packs uploaded by Freesound user USERNAME, returning a hash table with the sound list response.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id72

Package

freesound.

Source

freesound.lisp.

Function: user-sounds (username &key page page-size fields descriptors normalized)

Retrieve information about the sounds uploaded by Freesound user USERNAME, returning a hash table with the sound list response.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id71

Package

freesound.

Source

freesound.lisp.


5.2 Internals


5.2.1 Special variables

Special Variable: *root-uri*
Package

freesound.

Source

freesound.lisp.


5.2.2 Ordinary functions

Function: commas (lst)
Package

freesound.

Source

freesound.lisp.

Function: description-tags-format (tags)
Package

freesound.

Source

freesound.lisp.

Function: ensure-commas (in)
Package

freesound.

Source

freesound.lisp.

Function: ensure-list-of-lists (lst)
Package

freesound.

Source

freesound.lisp.

Function: http-parameters (plist)
Package

freesound.

Source

freesound.lisp.

Function: oauth2-get-tokens (code &key token client-id refresh)

Return the OAuth2 access token and a refresh token. CODE is either the initial authorization code, or a previously generated refresh token. In this second case, REFRESH must be T. Also set *oauth2-access-token* to the new value.

Package

freesound.

Source

freesound.lisp.

Function: optional-params-list (names params)
Package

freesound.

Source

freesound.lisp.

Function: parse-filter (filter)
Package

freesound.

Source

freesound.lisp.

Function: parse-target (target)
Package

freesound.

Source

freesound.lisp.

Function: prepare-plist (plist)
Package

freesound.

Source

freesound.lisp.

Function: print-columns (k v level stream)
Package

freesound.

Source

freesound.lisp.

Function: resource (uri &key method content authentication token oauth2-access-token)
Package

freesound.

Source

freesound.lisp.

Function: spaces (string)
Package

freesound.

Source

freesound.lisp.

Function: system-relative-read-file (filename)
Package

freesound.

Source

freesound.lisp.

Function: translate-license (license)
Package

freesound.

Source

freesound.lisp.

Function: translate-preview-format (format)
Package

freesound.

Source

freesound.lisp.

Function: uri (resource &optional root)
Package

freesound.

Source

freesound.lisp.

Function: user-bookmark-category-sounds (username &key bookmark-category-id page page-size fields descriptors normalized)

Retrieve information about the sounds from a bookmark category created by Freesound user USERNAME, returning a hash table with the sound list response.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id74

Package

freesound.

Source

freesound.lisp.

Function: user-info (username)

Retrieve information about Freesound user USERNAME.

API documentation: https://freesound.org/docs/api/resources_apiv2.html#id70

Package

freesound.

Source

freesound.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   B   C   D   E   F   H   I   M   O   P   R   S   T   U  
Index Entry  Section

A
analysis: Public ordinary functions

B
bookmark: Public ordinary functions

C
combined-search: Public ordinary functions
commas: Private ordinary functions
comment: Public ordinary functions
comments: Public ordinary functions
content-search: Public ordinary functions

D
describe-sound: Public ordinary functions
description-tags-format: Private ordinary functions
descriptors: Public ordinary functions
download: Public ordinary functions

E
edit-sound-description: Public ordinary functions
ensure-commas: Private ordinary functions
ensure-list-of-lists: Private ordinary functions

F
Function, analysis: Public ordinary functions
Function, bookmark: Public ordinary functions
Function, combined-search: Public ordinary functions
Function, commas: Private ordinary functions
Function, comment: Public ordinary functions
Function, comments: Public ordinary functions
Function, content-search: Public ordinary functions
Function, describe-sound: Public ordinary functions
Function, description-tags-format: Private ordinary functions
Function, descriptors: Public ordinary functions
Function, download: Public ordinary functions
Function, edit-sound-description: Public ordinary functions
Function, ensure-commas: Private ordinary functions
Function, ensure-list-of-lists: Private ordinary functions
Function, http-parameters: Private ordinary functions
Function, info: Public ordinary functions
Function, me: Public ordinary functions
Function, oauth2-authorize: Public ordinary functions
Function, oauth2-get-tokens: Private ordinary functions
Function, optional-params-list: Private ordinary functions
Function, pack-download: Public ordinary functions
Function, pack-instance: Public ordinary functions
Function, pack-sounds: Public ordinary functions
Function, parse-filter: Private ordinary functions
Function, parse-target: Private ordinary functions
Function, pending-uploads: Public ordinary functions
Function, prepare-plist: Private ordinary functions
Function, preview: Public ordinary functions
Function, print-columns: Private ordinary functions
Function, print-info: Public ordinary functions
Function, print-search-result: Public ordinary functions
Function, rate: Public ordinary functions
Function, resource: Private ordinary functions
Function, similar: Public ordinary functions
Function, spaces: Private ordinary functions
Function, system-relative-read-file: Private ordinary functions
Function, text-search: Public ordinary functions
Function, translate-license: Private ordinary functions
Function, translate-preview-format: Private ordinary functions
Function, upload: Public ordinary functions
Function, uri: Private ordinary functions
Function, user-bookmark-categories: Public ordinary functions
Function, user-bookmark-category-sounds: Private ordinary functions
Function, user-info: Private ordinary functions
Function, user-packs: Public ordinary functions
Function, user-sounds: Public ordinary functions

H
http-parameters: Private ordinary functions

I
info: Public ordinary functions

M
me: Public ordinary functions

O
oauth2-authorize: Public ordinary functions
oauth2-get-tokens: Private ordinary functions
optional-params-list: Private ordinary functions

P
pack-download: Public ordinary functions
pack-instance: Public ordinary functions
pack-sounds: Public ordinary functions
parse-filter: Private ordinary functions
parse-target: Private ordinary functions
pending-uploads: Public ordinary functions
prepare-plist: Private ordinary functions
preview: Public ordinary functions
print-columns: Private ordinary functions
print-info: Public ordinary functions
print-search-result: Public ordinary functions

R
rate: Public ordinary functions
resource: Private ordinary functions

S
similar: Public ordinary functions
spaces: Private ordinary functions
system-relative-read-file: Private ordinary functions

T
text-search: Public ordinary functions
translate-license: Private ordinary functions
translate-preview-format: Private ordinary functions

U
upload: Public ordinary functions
uri: Private ordinary functions
user-bookmark-categories: Public ordinary functions
user-bookmark-category-sounds: Private ordinary functions
user-info: Private ordinary functions
user-packs: Public ordinary functions
user-sounds: Public ordinary functions