freesound-client
Version:
 [](http://badge.fury.io/js/freesound-client) [](https://
501 lines (500 loc) • 16.2 kB
TypeScript
export interface Comment {
username: string;
comment: string;
created: string;
}
interface RawPack {
id: number;
url: string;
description: string;
created: string;
name: string;
username: string;
num_sounds: number;
num_downloads: number;
}
export interface Pack extends RawPack {
download: Function;
sounds: Function;
}
interface RawUser {
url: string;
username: string;
about: string;
home_page: string;
avatar: {
small: string;
large: string;
medium: string;
};
date_joined: string;
num_sounds: number;
num_packs: number;
num_posts: number;
num_comments: number;
bookmark_categories: string;
}
export interface User extends RawUser {
sounds: Function;
packs: Function;
bookmarkCategories: Function;
bookmarkCategorySounds: Function;
}
export interface AccessTokenResponse {
/**
* The value of the access token
*/
access_token: string;
scope: string;
/**
* The time in seconds until the access token exprires
*/
"expires_in": number;
/**
* Refresh token is used to update the expirey time of the access token
*/
"refresh_token": string;
}
interface RawCollection<T> {
count: number;
results: T[];
next: string;
previous: string;
}
export interface Collection<T> extends RawCollection<T> {
nextOrPrev: (page: string) => Promise<Collection<T>>;
nextPage: (page: number) => Promise<Collection<T>>;
previousPage: (page: number) => Promise<Collection<T>>;
getItem: (page: number) => T;
}
export interface SoundCollection extends Collection<Sound> {
getSound: (idx: number) => Sound;
}
interface RawSound {
/**
* Sound ID on Freesound.
*/
id: number;
/**
* The URl for this sound on the Freesound website.
*/
url: string;
/**
* The name user gave to the sound.
*/
name: string;
/**
* An array of tags the user gave to the sound.
*/
tags: string[];
/**
* The description the user gave to the sound.
*/
description: string;
geotag: null;
/**
* The date when the sound was uploaded (e.g. “2014-04-16T20:07:11.145”).
*/
created: string;
/**
* The license under which the sound is available to you.
*/
license: string;
/**
* The type of sound (wav, aif, aiff, mp3, m4a or flac).
*/
type: string;
/**
* The number of channels.
*/
channels: number;
/**
* The size of the file in bytes.
*/
filesize: number;
/**
* The bit rate of the sound in kbps.
*/
bitrate: number;
/**
* The bit depth of the sound.
*/
bitdepth: number;
/**
* The duration of the sound in seconds.
*/
duration: number;
/**
* The samplerate of the sound.
*/
samplerate: number;
/**
* The username of the uploader of the sound.
*/
username: string;
/**
* If the sound is part of a pack, this URl points to that pack’s API resource.
*/
pack: string;
pack_name?: string;
previews: {
'preview-lq-ogg': string;
'preview-lq-mp3': string;
'preview-hq-ogg': string;
'preview-hq-mp3': string;
};
images: {
spectral_m: string;
spectral_l: string;
spectral_bw_l: string;
waveform_bw_m: string;
waveform_bw_l: string;
waveform_l: string;
waveform_m: string;
spectral_bw_m: string;
};
/**
* The number of times the sound was downloaded.
*/
num_downloads: number;
/**
* The average rating of the sound.
*/
avg_rating: number;
/**
* The number of times the sound was rated.
*/
num_ratings: number;
/**
* The URl of a paginated list of the comments of the sound.
*/
comments: string;
num_comments: number;
/**
* URI pointing to the similarity resource (to get a list of similar sounds).
*/
similar_sounds: string;
analysis: string;
analysis_frames: string;
/**
* URL pointing to the complete analysis results of the sound (see Analysis Descriptor Documentation).
*/
analysis_stats: string;
/**
* Dictionary containing the results of the AudioCommons analysis for the given sound.
*/
ac_analysis: {
/**
* Reliability of the tempo estimation in a range of [0, 1].
*/
ac_tempo_confidence: number;
/**
* Reliability of the note name/midi/frequency estimation in a range of [0, 1].
*/
ac_note_confidence: number;
/**
* Depth of the analyzed audio in a scale from [0-100]. A deep sound is one that conveys the sense of having been made far down below the surface of its source.
*/
ac_depth: number;
/**
* MIDI value corresponding to the estimated note (makes more sense for ac_single_event sounds).
*/
ac_note_midi: number;
/**
* Temporal centroid (sec.) of the audio signal. It is the point in time in a signal that is a temporal balancing point of the sound event energy.
*/
ac_temporal_centroid: number;
/**
* Warmth of the analyzed sound in a scale from [0-100]. A warm sound is one that promotes a sensation analogous to that caused by a physical increase in temperature.
*/
ac_warmth: number;
/**
* Whether audio file is loopable.
*/
ac_loop: boolean;
ac_hardness: number;
/**
* The integrated (overall) loudness (LUFS) measured using the EBU R128 standard.
*/
ac_loudness: number;
/**
* Whether the signal is reverberated or not.
*/
ac_reverb: boolean;
/**
* Roughness of the analyzed audio in a scale from [0-100]. A rough sound is one that has an uneven or irregular sonic texture.
*/
ac_roughness: number;
ac_log_attack_time: number;
/**
* Boominess of the analyzed sound in a scale from [0-100]. A boomy sound is one that conveys a sense of loudness, depth and resonance.
*/
ac_boominess: number;
/**
* Frequency corresponding to the estimated note (makes more sense for ac_single_event sounds).
*/
ac_note_frequency: number;
/**
* BPM value estimated by beat tracking algorithm.
*/
ac_tempo: number;
/**
* Brightness of the analyzed audio in a scale from [0-100]. A bright sound is one that is clear/vibrant and/or contains significant high-pitched elements.
*/
ac_brightness: number;
/**
* Sharpness of the analyzed sound in a scale from [0-100]. A sharp sound is one that suggests it might cut if it were to take on physical form.
*/
ac_sharpness: number;
/**
* Reliability of the key estimation in a range of [0, 1].
*/
ac_tonality_confidence: number;
/**
* Loudness range (dB, LU) measured using the EBU R128 standard.
*/
ac_dynamic_range: number;
ac_note_name: string;
ac_tonality: string;
/**
* Whether the audio file contains one single audio event or more than one. This computation is based on the loudness of the signal and does not do any frequency analysis.
*/
ac_single_event: boolean;
};
}
export interface Sound extends RawSound {
getAnalysis: Function;
getSimilar: Function;
getComments?: Function;
rate: Function;
comment?: Function;
download: Function;
bookmark: Function;
edit?: Function;
}
declare type SearchOpts = {
analysis_file?: string;
target?: string;
query?: string;
filter?: string;
descriptors_filter?: string;
};
declare type TextSearchOpts = {
page?: number;
query?: string;
filter?: string;
sort?: string;
fields?: string;
group_by_pack?: 1 | 0;
};
export default class FreeSound {
private authHeader;
private clientId;
private clientSecret;
private host;
private uris;
private checkOauth;
private makeFormData;
search<T>(options: SearchOpts, uri: string): Promise<T>;
private Collection;
private SoundCollection;
private PackCollection;
private SoundObject;
private UserObject;
private PackObject;
/**
*
* There are two ways of authenticating: OAuth and token method.
* The OAuth method is required for more privilidged actions such as
* downloading sounds.
*
* This method can set both kinds of tokens
*
* ```typescript
* await freeSound.setToken('your-api-key', 'oauth');
* ```
*/
setToken(token: string, type?: "oauth"): string;
/**
* Set the credentials supplied by https://freesound.org/apiv2/apply for API
* call authentication. See
* https://freesound.org/docs/api/authentication.html?highlight=secret#token-authentication
* for more information.
*
* @param id your client ID, obtainable at https://freesound.org/apiv2/apply
* @param secret your client secret, obtainable at https://freesound.org/apiv2/apply
*
* ```typescript
* await freeSound.setClientSecrets(
* "your-client-id",
* "your-secret-key"
* );
* ```
*/
setClientSecrets(id: string, secret: string): void;
/**
* This method allows you to get a new token using a refresh token or an auth
* token
*
* ```typescript
* await freeSound.postAccessCode('your-temporary-code-from-login');
* ```
*/
postAccessCode(token: string, type?: 'refresh' | 'auth'): Promise<AccessTokenResponse>;
/**
* Search sounds in Freesound by matching their tags and other kinds of metadata. See
* https://freesound.org/docs/api/resources_apiv2.html#sound-text-search for more
* information.
*
* ```typescript
* await freeSound.textSearch('violoncello', {
* page: 1,
* filter: 'tag:tenuto duration:[1.0 TO 15.0]',
* sort: 'rating_desc',
* fields: 'id,name,url'
* });
* ```
*/
textSearch(query: string, opts?: TextSearchOpts): Promise<SoundCollection>;
/**
* Search sounds in Freesound based on their content descriptors. See
* https://freesound.org/docs/api/resources_apiv2.html#content-search
* for more information.
*
* ```typescript
* const result = await freeSound.contentSearch({
* target: 'lowlevel.pitch.mean:220',
* });
* ```
*/
contentSearch(options: SearchOpts): Promise<SoundCollection>;
/**
* Search sounds in Freesound based on their tags, metadata and content-based descriptiors via
* a combination of text search and content search. See
* https://freesound.org/docs/api/resources_apiv2.html#combined-search for more information.
*
* ```typescript
* const soundCollectionResults = await freeSound.combinedSearch(
* filter: 'tag:scale',
* target: 'rhythm.bpm:120',
* );
* ```
*/
combinedSearch(options: SearchOpts): Promise<unknown>;
/**
* Upload an audio file into Freesound and optionally describe it.
* If there is no file description, only the audio file will upload, and
* the user will need to add a description later using
* the describe(description: { description: string }) method. If the file description
* is present, the uploaded file will be ready for the processing and moderation stage.
* A list of uploaded files pending a description, processing or moderation is
* obtainable through the getPendingSounds() method. See
* https://freesound.org/docs/api/resources_apiv2.html#upload-sound-oauth2-required
* for more information. This method requires OAuth2 authentication.
*
* @param audiofile the audio file to upload
* @param filename the name of the audio file to upload
* @param description the description of the audio file to upload
*/
upload(audiofile: string, filename: string, description: {
description: string;
}): Promise<unknown>;
/**
* Describe a previously uploaded file that does not have a description.
* Note: after a sound receives a description, the team of Freesound moderators
* still needs to process and moderate it, so it may not yet appear in Freesound.
* A list of sounds uploaded and described by the user, but still
* pending processing and moderation, is viewable with
* the getPendingSounds() method. This method requires OAuth2 authentication. See
* https://freesound.org/docs/api/resources_apiv2.html#describe-sound-oauth2-required
* for more information.
*
* @param description a description for an uploaded sound
*/
describe(description: {
description: string;
}): Promise<unknown>;
/**
* Retrieve a list of audio files uploaded by he Freesound user logged in using
* OAuth2 are not described, processed or moderated. In Freesound, sounds need
* descriptions after their upload. Then, sounds are automatically processed, and,
* finally, a team of human moderators either accepts or rejects the upload. This method
* keeps track of the status of these uploads and requires OAuth2 authentication. See
* https://freesound.org/docs/api/resources_apiv2.html#pending-uploads-oauth2-required
* for more information.
*
* ```typescript
* const result = await freeSound.getPendingSounds()
* ```
*/
getPendingSounds(): Promise<unknown>;
/**
* Return basic information about the user that is logged in via OAuth2.
* This application can use it to identify which Freesound user has logged in.
*
* ```typescript
* const result = await freeSound.me();
* ```
*/
me(): Promise<unknown>;
/**
* Navigate to Freesound for user login.
*
* @returns a url where the user can login
*
* ```typescript
* const navigateToLogin = () => {
* window.location.replace(freeSound.getLoginURL());
* };
* ```
*/
getLoginURL(): string;
getLogoutURL(): string;
/**
* Retrieve information about a particular Freesound user. See
* https://freesound.org/docs/api/resources_apiv2.html#user-instance
* for more information.
*
* @param username the username of the Freesound user
* @returns information about a particular Freesound user
*
* ```typescript
* // Get information about the user https://freesound.org/people/MTG/.
* const user = await freeSound.getUser('MTG');
* ```
*/
getUser(username: string): Promise<User>;
/**
* Retrieve the list of sounds included in a pack. See
* https://freesound.org/docs/api/resources_apiv2.html#pack-sounds for more information.
*
* @param packId the identification number of the pack to fetch
* @returns a list of sounds included in the pack that has packId as its identification number
*
* ```typescript
* // Fetch the pack
* // https://freesound.org/people/vroomvro0om/packs/21143/.
* const packObj = await freeSound.getPack(21143);
* ```
*/
getPack(packId: string | number, options?: {}): Promise<Pack>;
/**
* Retrieve detailed information about a sound. See
* https://freesound.org/docs/api/resources_apiv2.html#sound-resources
* for more information.
*
* @param soundId the identification number of the sound
* @returns detailed information about a sound
*
* ```typescript
* // Fetch the sound
* // https://freesound.org/people/vroomvro0om/sounds/376626/.
* const fetchedSound = await freeSound.getSound(376626);
* ```
*/
getSound(soundId: string | number): Promise<Sound>;
private makeUri;
private fetchWithAuthParams;
private makeRequest;
}
export {};