@percuss.io/soundslice-data-api
TypeScript icon, indicating that this package has built-in type declarations

0.19.4 • Public • Published

soundslice-data-api

Unofficial Node.js client for the Soundslice data API

1. Install

https://www.npmjs.com/package/@percuss.io/soundslice-data-api

$ npm install @percuss.io/soundslice-data-api

2. Import & Instantiate the Client

// Soundslice data API keys from
// https://www.soundslice.com/help/data-api/
const { SOUNDSLICE_APPLICATION_ID, SOUNDSLICE_PASSWORD } = process.env;

// create an instance of the Soundslice data API client
const apiClient = require('@percuss.io/soundslice-data-api').default({
  SOUNDSLICE_APPLICATION_ID,
  SOUNDSLICE_PASSWORD,
});

3. Usage

See the examples folder on GitHub for detailed usage examples.

apiClient.listSlices().then(handleSuccess).catch(handleError);

function handleSuccess(res) {
  const { data } = res;

  console.log(data);
}

function handleError(err) {
  const { response } = err;

  console.error(response.status);
  console.error(response.statusText);
}

Client Methods

Each method returns an Axios Promise.

NOTE: Not all API methods have been implemented yet.

createSlice(paramsObj)

// all params are optional
apiClient.createSlice({
  // "Title" in Soundslice's form modal
  name: 'The Quick Brown Fox',

  artist: 'Lazy Dog',

  // allow embedding on whitelist domains
  // disabled when omitted
  embed_status: 4,

  // the folder in which to create the slice
  // created in the root folder when omitted
  folder_id: '12345',

  // allow printing
  // disallowed when omitted
  print_status: 3,

  // viewable by anyone who knows its URL
  // private when omitted
  status: 3,
})

duplicateSliceByScorehash(scorehash)

  • Deletes the slice with scorehash scorehash, including all its associated data such as recordings.
  • Soundslice documentation: "Delete slice"
apiClient.duplicateSliceByScorehash('abcde')

deleteSliceBySlug(slug) (deprecated)

  • DEPRECATED Use duplicateSliceByScorehash instead.
  • Deletes the slice with slug slug.
apiClient.deleteSliceBySlug('123456')

listSlices()

  • Retrieves metadata for all slices in your account.
  • Soundslice documentation: "List slices"
  • This method takes no arguments.
apiClient.listSlices()

getSliceByScorehash(scorehash)

  • Retrieves metadata for the slice with scorehash scorehash.
  • Soundslice documentation: "Get slice"
apiClient.getSliceByScorehash('abcde')

getSliceBySlug(slug) (deprecated)

  • DEPRECATED Use getSliceByScorehash instead.
  • Retrieves metadata for the slice with slug slug.
apiClient.getSliceBySlug('123456')

getSliceNotationByScorehash(scorehash)

  • Retrieves the original notation file for the slice with scorehash scorehash.
  • Soundslice documentation: "Get slice’s notation"
apiClient.getSliceNotationByScorehash('abcdef')

getSliceNotationBySlug(slug)

apiClient.getSliceNotationBySlug('123456')

moveSliceToFolder(paramsObj)

apiClient.moveSliceToFolder({
  // Required - The slice's slug.
  slug: '123456',

  // Required - The ID of the new folder.
  // Use 0 (zero) to move the slice to your account's root folder.
  folder_id: '2048',

  // Optional - The ID of the user account to move this slice into.
  // This will only work for the ID of an organization you belong to.
  // If not provided, this value will default to the user you're accessing the
  // API with.
  user_id: 4,
})

duplicateSliceByScorehash(scorehash)

  • Duplicates the slice with the scorehash scorehash.
  • Soundslice documentation: "Duplicate slice"
apiClient.duplicateSliceByScorehash('C1FVc')

getSliceRecordingsByScorehash(scorehash)

apiClient.getSliceRecordingsByScorehash('HD8Nc')

getSliceRecordingsBySlug(slug) (deprecated)

  • DEPRECATED Use getSliceRecordingsByScorehash instead.
  • Gets data about all recordings in the slice with slug slug.
apiClient.getSliceRecordingsBySlug('123456')

reorderSliceRecordings(paramsObj)

  • Reorder a slice's recordings.
  • Sets the order of the recordings in the slice with a given scorehash.
  • Soundslice documentation: "Reorder slice’s recordings"
apiClient.reorderSliceRecordings({
  // The slice whose recordings you'd like to reorder.
  scorehash: 'abcde',

  // An array of recording IDs in your requested order.
  // **OR** a string of recording IDs separated by commas.
  //
  // The first recording ID is the top-most recording in the Soundslice UI, and so forth.
  // The last recording ID is the default.
  // Every recording in the slice must be included in this data.
  order: [222226, 222227, 222225],

  // Optionally, pass a comma-delimited string:
  // order: '222226,222227,222225'
})

changeRecording(paramsObj)

  • Changes data for the recording with ID recordingId.
  • It's possible change a recording's name, and/or source_data, and/or hls_url.
  • Makes a POST request with the given parameters.
  • Other than recordingId, all params are optional.
  • If you don’t want to change a particular value, simply don't send its key with the request.
  • Soundslice documentation: "Change recording"
apiClient.changeRecording({
  // Required
  recordingId: 123456,

  // The attribute of the recording that you'd like to change.
  name: 'Changed Recording Name',

  // Optionally, 'source_data' can be changed if `source` is 3 or 8.

  // Optionally, 'hls_url' can be changed if `source` is 3.
})

deleteRecordingByRecordingId(recordingId)

  • Deletes the recording with the given recordingId, including all its associated data such as syncpoints and uploaded audio.
  • Soundslice documentation: "Delete recording"
apiClient.deleteRecordingByRecordingId('123456')

getSyncpointsByRecordingId(recordingId)

apiClient.getSyncpointsByRecordingId('123456')

putRecordingSyncpoints(paramsObj)

apiClient.putRecordingSyncpoints({
  // Required
  recordingId: '494055',

  // Required - an array of syncpoint arrays
  //   each entry is an array with the following numbers:
  //   index 0 - bar (required)
  //   index 1 - time (required)
  //   index 2 - percentage into the bar (optional)
  //             between 0 & 480 (50% is 240)
  syncpoints: [
    [0, 0],
    [1, 0.57],
    [1, 0.8, 240],
    [2, 1.3],
  ],

  // Optional - floating-point number
  // crop_start: 59.0,

  // Optional - floating-point number
  // crop_end: 65.0,
})

createFolder(paramsObj)

apiClient.createFolder({
  // Required - The name of the folder.
  name: 'New Example Folder',

  // Optional - Integer. The folder's parent ID.
  // Use this if you want to nest a folder within another one.
  parent_id: 12345,
})

renameFolder(paramsObj)

apiClient.renameFolder({
  // Required - The folder's ID.
  folderId: '12345',

  // Required - The new name of the folder.
  name: 'Renamed Folder',
})

deleteFolderByFolderId(folderId)

  • Deletes the given folder within your account’s slice manager.
  • The folder must be empty. It can’t contain any slices or other folders.
  • Soundslice documentation: "Delete folder"
apiClient.deleteFolderByFolderId('12345')

listFolders()

  • Lists top-level folders within your account’s slice manager.
  • Soundslice documentation: "List folders"
  • This method takes no arguments.
apiClient.listFolders()

listSubfoldersByParentId(parentId)

  • List subfolders within a given parent folder.
  • Soundslice documentation: "List folders"
apiClient.listSubfoldersByParentId('12345')

Methods for Uploading Media

Uploading media is a multi-step process. Here's a high-level example of a three-step process to upload a recording:

  • STEP 1: Call apiClient.createRecording with the slug of the slice. This will return an object with an id property of the new recording.
  • STEP 2: Call apiClient.getRecordingUploadUrlByRecordingId with the id from step 1 as recordingId. This will return an object with a url property.
  • STEP 3: Call apiClient.uploadFile with the url from step 2 as uploadUrl.

Uploading Notation

  • STEP 1: Call apiClient.getNotationUploadUrlByScorehash with the scorehash of the slice. This will return an object with a url property.
  • STEP 2: Call apiClient.uploadFile with the url from step 1 as uploadUrl.

See the examples folder on GitHub for information about using these methods.

Versioning

Until this package reaches a 1.0 release, breaking changes may be released.

BREAKING CHANGES

  • Starting with v0.14.0, environments using a CommonJS import system (i.e. vanilla Node.js with require statements) may need to append .default when importing this package.

Readme

Keywords

Package Sidebar

Install

npm i @percuss.io/soundslice-data-api

Weekly Downloads

1

Version

0.19.4

License

ISC

Unpacked Size

50.3 kB

Total Files

13

Last publish

Collaborators

  • ericcarraway