声音切片Python API库

此库允许您从Python使用声音切片数据API。

安装

pip install soundsliceapi

使用

注意：所有这些方法都需要一个声音切片API密钥。请按照此处说明获取一个。

每个方法都使用一个Client对象，该对象需要您的API信息

from soundsliceapi import Client
client = Client(APP_ID, PASSWORD)

可用方法包括

create_slice(**kwargs)

创建一个切片。注意，这只会创建切片的元数据，而不是乐谱。

from soundsliceapi import Constants

client.create_slice(
    #  All fields optional.
    name='The Power of Love',

    artist='Huey Lewis and the News',

    # Slice URL is private by default.
    has_shareable_url=True,

    # Embedding is disabled by default. To enable pass
    # EMBED_STATUS_ON_ALLOWLIST.
    embed_status=Constants.EMBED_STATUS_ON_ALLOWLIST,

    # Printing is disabled by default.
    can_print=True,

    # A string specifying the ID of the folder in which to put the slice.
    # If you don't specify this, it will be placed in the account's root folder.
    folder_id='31045'
)

返回包含以下键的切片信息字典

键	示例	注释
"scorehash"	"nyfcn"	切片的scorehash。这是一个最大长度为6个字符的唯一标识符。
"url"	"/slices/nyfcn/"	在声音切片.com上的切片URL。注意，这个URL在切片有乐谱之前会返回404。
"embed_url"	"/slices/nyfcn/embed/"	仅当切片启用了嵌入时才包含。这是您需要在 <iframe> 中放置的 URL。注意，此 URL 将返回 404 错误，直到切片有符号。

delete_slice(scorehash)

删除一个切片，包括所有相关数据，如录音。

client.delete_slice("scorehash")

返回包含以下键的切片信息字典

键	示例	注释
"name"	"Sussudio"	字符串。切片的名称。
"artist"	"Phil Collins"	字符串。切片的艺术家。可能为空字符串，但它在 JSON 中始终存在。

list_slices()

检索您账户中所有切片的元数据。结果中切片的顺序是未定义的。

client.list_slices()

返回包含以下键的切片信息字典

键	示例	注释
"scorehash"	"nyfcn"	这是一个最大长度为 6 个字符的唯一标识符。
"url"	"/slices/MpYDc/"	字符串。slice 在 soundslice.com 上的 URL。注意，如果切片没有符号，此 URL 将返回 404 错误。
"name"	"Take Me Home Tonight"	字符串。切片的名称。
"artist"	"Eddie Money"	字符串。切片的艺术家。可能为空字符串，但它在 JSON 中始终存在。
"status"	1	整数。切片的密钥 URL 状态。 1 — 密钥 URL 已禁用（默认值，如果未提供） 3 — 密钥 URL 已启用
"embed_status"	1	整数。切片的嵌入状态。 1 — 禁用（默认值，如果未提供） 4 — 允许列表域上启用
"can_print"	False	布尔值。切片是否可以打印。
"has_notation"	True	布尔值。切片是否有符号。
"show_notation"	True	布尔值。切片是否可以显示其符号。除非您在切片管理器中手动禁用符号，否则此值为 true。
"recording_count"	3	整数。切片的录音数量。
"embed_url"	"/slices/d8sDc/embed/"	字符串。切片的嵌入 URL。注意，如果切片没有符号，此 URL 将返回 404 错误，并且如果切片无法嵌入，则此键将不在 JSON 中。

get_slice(scorehash)

检索切片的元数据。成功时，返回与 list_slices() 方法中记录的相同键的字典。

client.get_slice("scorehash")

get_original_slice_notation_file(scorehash)

检索切片的原始符号文件。这是一个我们支持的一种格式（例如，MusicXML、GPX 等）的文件。如果您已上传多个文件，则返回最近上传的文件。

client.get_original_slice_notation_file('scorehash')

成功返回包含以下键的字典

键	示例	注释
"url"	"https://soundslice-data.s3.amazonaws.com/json/592129/rawscore?response…"	这是一个您可以在接下来的 15 分钟内下载原始符号文件的 URL。 注意 "url" 对于没有原始符号文件的切片将被设置为空字符串。

get_slice_musicxml(scorehash)

为切片生成 MusicXML。

注意，这使用基于切片当前符号的我们自己的 MusicXML 导出算法。如果您通过上传 MusicXML 文件创建了切片，则不会返回该文件；您可以另外 获取切片的原始符号

client.get_slice_musicxml('scorehash')

成功返回包含切片 MusicXML 的字符串。

upload_slice_notation(**kwargs)

将符号文件上传到给定的切片。

此 API 方法仅可通过特殊权限访问。如果您想获得访问权限，请 联系我们 并告诉我们您打算如何使用它。

client.upload_slice_notation(
    scorehash="n4nrf",

    # File-like object containing the raw notation data.
    fp=open("~/tmp/notation/score.xml", "r"),

    # An optional URL that Soundslice will POST to when the upload is processed.
    # Should be a full path, starting with http:// or https://.
    callback_url=None
)

如果提供了 callback_url，我们将在上传处理完成后通过向您指定的 URL 发送 POST 通知您。这些 POST 请求将包括以下键

键	示例	注释
"scorehash"	"d8sDc"	字符串。新创建的切片的 scorehash。
"success"	"1"	字符串。如果成功处理，则为 "1"。如果出错，则为 "2"。
"error"	"我们无法解析提供的文件."	字符串。错误消息，如有错误。

move_slice_to_folder(**kwargs)

将切片移动到给定的文件夹，可以是您自己的账户或您所属的组织。

client.move_slice_to_folder(
    # Required scorehash
    scorehash="n4nrf",

    # Required ID of the new folder.
    # Use folder_id 0 (zero) to move the slice to your account’s root folder.
    folder_id=0,
)

成功时，返回包含以下键的字典

键	示例	注释
"id"	0	整数。文件夹的 ID，或 0（零）为根文件夹。

duplicate_slice(scorehash)

复制一个切片，这个切片必须存在于您的账户中。新创建的切片将位于您的切片管理器的顶层。

client.duplicate_slice("scorehash")

以下是要复制的项目

• 标题和元数据（除创建日期外）
• 符号数据
• 所有录音
• 所有同步点

切片版本历史不会复制。

您将立即收到新创建切片的信息。请注意，符号、录音和同步点可能尚未复制；这取决于我们消息队列的当前负载，可能需要几秒钟。

成功时，返回一个字典，其键与create_slice()方法中记录的键相同。

create_recording(**kwargs)

创建一个录音。

from soundsliceapi import Constants

client.create_recording(
    # Required scorehash.
    scorehash="n4nrf",

    # Required. Pass one of the following constants:
        # Constants.SOURCE_MP3_UPLOAD
        # Constants.SOURCE_VIDEO_UPLOAD
        # Constants.SOURCE_VIDEO_URL
        # Constants.SOURCE_MP3_URL
        # Constants.SOURCE_YOUTUBE
        # Constants.SOURCE_VIMEO
        # Constants.SOURCE_WISTIA
    source=Constants.SOURCE_YOUTUBE,

    # Required for some sources. See table below.
    source_data="dQw4w9WgXcQ",

    # Applicable only if source is Constants.SOURCE_VIDEO_URL.
    # The value is not required if you provide source_data.
    # You can provide both hls_url and source_data; in that case,
    # our player will use the hls_url for users whose
    # browsers support HLS and source_data otherwise.
    hls_url=None,

    # Required if source is Constants.SOURCE_MP3_UPLOAD
    # or Constants.SOURCE_VIDEO_UPLOAD.
    filename=None
)

source_data的值根据录音源的不同而不同，如下所示

如果来源是...	示例source_data	注释
SOURCE_YOUTUBE	"dQw4w9WgXcQ"	YouTube视频的URL或ID。必需。
SOURCE_VIDEO_URL	"https://www.rmp-streaming.com/media/big-buck-bunny-360p.mp4"	视频的URL。必需提供此URL或hls_url（您也可以两者都提供）。
SOURCE_VIMEO	"253989945"	视频的Vimeo ID。必需。
SOURCE_WISTIA	"j38ihh83m5"	视频的Wistia ID。必需。
SOURCE_MP3_URL	"https://stream.thisamericanlife.org/31/31.mp3"	MP3的URL。必需。

get_slice_recordings(scorehash)

获取给定切片中所有录音的数据。成功时，返回一个字典，具有以下键

键	示例	注释
"id"	626940	录音的ID。
"name"	"Video"	录音的名称。
"source"	1	录音的source（有关详细信息，请参见上面）。
"source_data"	"eBG7P-K-r1Y"	录音的source data（有关详细信息，请参见上面）。
"hls_url"	""	录音的HLS URL，或空字符串。
"cropped_duration"	289.0	考虑裁剪的录音时长，以秒为单位。例如，如果原始录音为60秒长，但您已裁剪以删除前10秒，则cropped_duration将为50。对于没有时长的录音，例如仍在处理的录音，将设置为null。
"syncpoint_count"	8	录音的同步点数量。
"status"	"ready"	录音的状态。可能的值包括 waiting — 等待上传媒体 processing — 处理上传的媒体 ready — 准备就绪 error — 遇到处理错误

reorder_slice_recordings(**kwargs)

设置切片中录音的顺序。

client.reorder_slice_recordings(
    scorehash="78sDc",

    # A string of recording IDs separated by commas, in your requested order.
    # 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="123,124,121"
)

成功时，结果将是一个空JSON对象。

change_recording(**kwargs)

更改录音的元数据。

client.change_recording(
    # All are optional; if you don’t want to change a particular value, simply
    # don’t send its key with the request.
    name="YouTube performance",

    # Only available for video URLs and audio URLs.
    source_data="IuUwyIPSgnQ",

    # Only available for video URLs.
    hls_url=""
)

成功时，返回一个字典，具有以下键

键	示例	注释
"id"	626940	录音的ID。
"name"	"YouTube performance"	录音的名称。
"source_data"	"IuUwyIPSgnQ"	录音的source data（有关详细信息，请参见上面）。
"hls_url"	""	录音的HLS URL，或空字符串。

delete_recording(recording_id)

删除一个录音，包括所有相关数据，如同步点和上传的音频。

client.delete_recording("626940")

成功时，返回包含以下键的字典

键	示例	注释
"name"	"Video"	字符串。录音的名称。

get_recording_syncpoints(recording_id)

检索录音的同步点。

client.get_recording_syncpoints("626940")

成功时，返回一个表示同步点的JSON列表。请参阅同步点数据格式。

put_recording_syncpoints(**kwargs)

设置录音的同步点。

client.put_recording_syncpoints(
    # Required.
    recording_id="626940",

    # Required. See syncpoint data format link above.
    syncpoints=[[0, 0], [1, 0.57], [1, 0.8, 240], [2, 1.3]],

    # Optional. Number of seconds into the recording to start cropping
    # (a float). For example, if this is 12, then the recording will begin
    #  playback at 12 seconds, and seconds 0-12 will be inaccessible.
    crop_start=12,

    # Optional. Number of seconds into the recording to end cropping
    # (a float). For example, if this is 60, then the recording will end
    #  playback at the timecode 60 seconds, and any audio after timecode 60
    # seconds will be inaccessible. Note this is relative to the absolute
    # recording, so crop_start has no effect on crop_end.
    crop_end=60
)

成功时，返回包含以下键的字典

键	示例	注释
"id"	626940	录音ID，作为整数。

create_folder(**kwargs)

在您的账户切片管理器中创建一个文件夹。

client.create_folder(
    # Required.
    name="Practice list",

    # Optional. The folder’s parent ID. Use this if you want to nest a folder
    # within another one.
    parent_id=31043
)

成功返回包含以下键的字典

键	示例	注释
"id"	31044	新创建的文件夹的ID。

rename_folder(**kwargs)

重命名您的账户切片管理器中的给定文件夹。

# All required.
folder_id=31044,

name="New practice list"

成功时，返回包含以下键的字典

键	示例	注释
"id"	31044	文件夹的ID。

delete_folder(folder_id)

删除您的账户切片管理器中的给定文件夹。

client.delete_folder(
    folder_id=31044
)

成功时，返回包含以下键的字典

键	示例	注释
"parent_id"	31043	被删除文件夹的父文件夹ID，如果被删除的文件夹在根目录中，则为None。

list_folders(**kwargs)

列出您的账户切片管理器中的所有文件夹。

默认情况下，此列表仅显示顶级文件夹。要列出给定文件夹内的子文件夹，请传递参数 parent_id。

client.list_folders(
    # Optional.
    parent_id=None
)