Skip to content

Commit ae6ecee

Browse files
gierschvgierschv
committed
feat(api): API specification v2.5
Add additional video & audio track support for scores (/v2/scores/{score}/tracks)
1 parent 0db9f1f commit ae6ecee

File tree

1 file changed

+319
-1
lines changed

1 file changed

+319
-1
lines changed

Diff for: ‎spec/swagger.yaml

+319-1
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ info:
3030
* [SDKs](https://flat.io/developers/docs/api/sdks.html)
3131
* [Rate Limits](https://flat.io/developers/docs/api/rate-limits.html)
3232
* [Changelog](https://flat.io/developers/docs/api/changelog.html)
33-
version: 2.4.0
33+
version: 2.5.0
3434
termsOfService: https://flat.io/legal
3535
contact:
3636
name: Flat
@@ -475,6 +475,160 @@ paths:
475475
schema:
476476
$ref: '#/definitions/FlatErrorResponse'
477477

478+
/scores/{score}/tracks:
479+
post:
480+
tags: [Score]
481+
security:
482+
- OAuth2:
483+
- scores
484+
summary: Add a new video or audio track to the score
485+
description: |
486+
Use this method to add new track to the score. This track can then be played on flat.io or in an embedded score.
487+
This API method support medias hosted on SoundCloud, YouTube and Vimeo.
488+
operationId: addScoreTrack
489+
parameters:
490+
- $ref: '#/parameters/score'
491+
- name: body
492+
in: body
493+
required: true
494+
schema:
495+
$ref: '#/definitions/ScoreTrackCreation'
496+
responses:
497+
200:
498+
description: Created track
499+
schema:
500+
$ref: '#/definitions/ScoreTrack'
501+
403:
502+
description: Not granted to access to this score
503+
schema:
504+
$ref: '#/definitions/FlatErrorResponse'
505+
404:
506+
description: Score not found
507+
schema:
508+
$ref: '#/definitions/FlatErrorResponse'
509+
default:
510+
description: Error
511+
schema:
512+
$ref: '#/definitions/FlatErrorResponse'
513+
get:
514+
tags: [Score]
515+
security:
516+
- OAuth2:
517+
- scores
518+
- scores.readonly
519+
summary: List the audio or video tracks linked to a score
520+
operationId: listScoreTracks
521+
parameters:
522+
- $ref: '#/parameters/score'
523+
- $ref: '#/parameters/scoreSharingKey'
524+
responses:
525+
200:
526+
description: List of tracks
527+
schema:
528+
type: array
529+
items:
530+
$ref: '#/definitions/ScoreTrack'
531+
403:
532+
description: Not granted to access to this score
533+
schema:
534+
$ref: '#/definitions/FlatErrorResponse'
535+
404:
536+
description: Score not found
537+
schema:
538+
$ref: '#/definitions/FlatErrorResponse'
539+
default:
540+
description: Error
541+
schema:
542+
$ref: '#/definitions/FlatErrorResponse'
543+
544+
/scores/{score}/tracks/{track}:
545+
get:
546+
tags: [Score]
547+
security:
548+
- OAuth2:
549+
- scores
550+
- scores.readonly
551+
summary: Retrieve the details of an audio or video track linked to a score
552+
operationId: getScoreTrack
553+
parameters:
554+
- $ref: '#/parameters/score'
555+
- $ref: '#/parameters/scoreSharingKey'
556+
- $ref: '#/parameters/scoreTrack'
557+
responses:
558+
200:
559+
description: Track details
560+
schema:
561+
$ref: '#/definitions/ScoreTrack'
562+
403:
563+
description: Not granted to access to this score
564+
schema:
565+
$ref: '#/definitions/FlatErrorResponse'
566+
404:
567+
description: Score or Track not found
568+
schema:
569+
$ref: '#/definitions/FlatErrorResponse'
570+
default:
571+
description: Error
572+
schema:
573+
$ref: '#/definitions/FlatErrorResponse'
574+
put:
575+
tags: [Score]
576+
security:
577+
- OAuth2:
578+
- scores
579+
summary: Update an audio or video track linked to a score
580+
operationId: updateScoreTrack
581+
parameters:
582+
- $ref: '#/parameters/score'
583+
- $ref: '#/parameters/scoreTrack'
584+
- name: body
585+
in: body
586+
required: true
587+
schema:
588+
$ref: '#/definitions/ScoreTrackUpdate'
589+
responses:
590+
200:
591+
description: Updated track
592+
schema:
593+
$ref: '#/definitions/ScoreTrack'
594+
403:
595+
description: Not granted to access to this score
596+
schema:
597+
$ref: '#/definitions/FlatErrorResponse'
598+
404:
599+
description: Score or Track not found
600+
schema:
601+
$ref: '#/definitions/FlatErrorResponse'
602+
default:
603+
description: Error
604+
schema:
605+
$ref: '#/definitions/FlatErrorResponse'
606+
delete:
607+
tags: [Score]
608+
security:
609+
- OAuth2:
610+
- scores
611+
summary: Remove an audio or video track linked to the score
612+
operationId: deleteScoreTrack
613+
parameters:
614+
- $ref: '#/parameters/score'
615+
- $ref: '#/parameters/scoreTrack'
616+
responses:
617+
204:
618+
description: Track removed
619+
403:
620+
description: Not granted to access to this score
621+
schema:
622+
$ref: '#/definitions/FlatErrorResponse'
623+
404:
624+
description: Score or Track not found
625+
schema:
626+
$ref: '#/definitions/FlatErrorResponse'
627+
default:
628+
description: Error
629+
schema:
630+
$ref: '#/definitions/FlatErrorResponse'
631+
478632
/scores/{score}/comments:
479633
post:
480634
tags: [Score]
@@ -1908,6 +2062,13 @@ parameters:
19082062
Unique identifier of a **collaborator permission**, or unique identifier of a **User**, or unique identifier of a **Group**
19092063
type: string
19102064
required: true
2065+
scoreTrack:
2066+
name: track
2067+
in: path
2068+
description: |
2069+
Unique identifier of a score audio track
2070+
type: string
2071+
required: true
19112072
scoreComment:
19122073
name: comment
19132074
in: path
@@ -2536,6 +2697,163 @@ definitions:
25362697
25372698
When using a [Flat for Education](https://flat.io/edu) account, some of the modes may not be available if disabled by an administrator of the organization (e.g. by default the `public` mode is not available).
25382699
2700+
ScoreTrack:
2701+
description: An audio track for a score
2702+
type: object
2703+
properties:
2704+
id:
2705+
description: The unique identifier of the score track
2706+
type: string
2707+
title:
2708+
description: Title of the track
2709+
type: string
2710+
score:
2711+
description: The unique identifier of the score
2712+
type: string
2713+
creator:
2714+
description: The unique identifier of the track creator
2715+
type: string
2716+
creationDate:
2717+
description: The creation date of the track
2718+
type: string
2719+
format: date-time
2720+
modificationDate:
2721+
description: The modification date of the track
2722+
type: string
2723+
format: date-time
2724+
default:
2725+
description: True if the track should be used as default audio source
2726+
type: boolean
2727+
state:
2728+
$ref: '#/definitions/ScoreTrackState'
2729+
type:
2730+
$ref: '#/definitions/ScoreTrackType'
2731+
url:
2732+
description: The URL of the track
2733+
type: string
2734+
mediaId:
2735+
description: |
2736+
The unique identifier of the track when hosted on an external service.
2737+
For example, if the url is `https://www.youtube.com/watch?v=dQw4w9WgXcQ`, `mediaId` will be `dQw4w9WgXcQ`
2738+
type: string
2739+
synchronizationPoints:
2740+
type: array
2741+
items:
2742+
$ref: '#/definitions/ScoreTrackPoint'
2743+
example:
2744+
id: 59ecb20e563736b1e1f75dce
2745+
title: Rick Astley - Never Gonna Give You Up
2746+
type: youtube
2747+
url: https://www.youtube.com/watch?v=dQw4w9WgXcQ
2748+
mediaId: dQw4w9WgXcQ
2749+
creationDate: 2017-10-22T14:58:22.753000Z
2750+
modificationDate: 2017-10-22T14:58:33.424000Z
2751+
default: true
2752+
state: completed
2753+
creator: 5815d4b53269d90d2c80b71c
2754+
score: 59a29d96f35a6411d7508bdd
2755+
synchronizationPoints:
2756+
- type: measure
2757+
time: 0
2758+
measureUuid: 5132a788-69e6-d0c6-84ec-4bd858658d7c
2759+
- type: end
2760+
time: 213
2761+
2762+
ScoreTrackCreation:
2763+
description: |
2764+
Creation of a new track. This one must contain the URL of the track or the corresponding file
2765+
type: object
2766+
properties:
2767+
title:
2768+
description: Title of the track
2769+
type: string
2770+
default:
2771+
description: True if the track should be used as default audio source
2772+
type: boolean
2773+
state:
2774+
$ref: '#/definitions/ScoreTrackState'
2775+
url:
2776+
description: The URL of the track
2777+
type: string
2778+
synchronizationPoints:
2779+
type: array
2780+
items:
2781+
$ref: '#/definitions/ScoreTrackPoint'
2782+
example:
2783+
title: Rick Astley - Never Gonna Give You Up
2784+
url: https://www.youtube.com/watch?v=dQw4w9WgXcQ
2785+
default: true
2786+
state: draft
2787+
synchronizationPoints:
2788+
- type: measure
2789+
time: 0
2790+
measureUuid: 5132a788-69e6-d0c6-84ec-4bd858658d7c
2791+
- type: end
2792+
time: 213
2793+
2794+
ScoreTrackUpdate:
2795+
description: |
2796+
Update an existing track.
2797+
type: object
2798+
properties:
2799+
title:
2800+
description: Title of the track
2801+
type: string
2802+
default:
2803+
description: True if the track should be used as default audio source
2804+
type: boolean
2805+
state:
2806+
$ref: '#/definitions/ScoreTrackState'
2807+
synchronizationPoints:
2808+
type: array
2809+
items:
2810+
$ref: '#/definitions/ScoreTrackPoint'
2811+
example:
2812+
title: Rick Astley - Never Gonna Give You Up
2813+
url: https://www.youtube.com/watch?v=dQw4w9WgXcQ
2814+
default: true
2815+
state: draft
2816+
synchronizationPoints:
2817+
- type: measure
2818+
time: 0
2819+
measureUuid: 5132a788-69e6-d0c6-84ec-4bd858658d7c
2820+
- type: end
2821+
time: 213
2822+
2823+
ScoreTrackPoint:
2824+
description: A track synchronization point
2825+
type: object
2826+
required:
2827+
- type
2828+
- time
2829+
properties:
2830+
type:
2831+
type: string
2832+
enum: [measure, end]
2833+
description: The type of the synchronization point. If the type is `measure`, the measure uuid must be present in `measureUuid`
2834+
measureUuid:
2835+
type: string
2836+
format: uuid
2837+
description: The measure unique identifier
2838+
time:
2839+
type: number
2840+
description: The corresponding time in seconds
2841+
example:
2842+
type: measure
2843+
time: 0
2844+
measureUuid: 5132a788-69e6-d0c6-84ec-4bd858658d7c
2845+
2846+
ScoreTrackType:
2847+
type: string
2848+
description: The type of an audio track
2849+
enum: [audio, soundcloud, youtube, vimeo]
2850+
2851+
ScoreTrackState:
2852+
description: State of the track
2853+
type: string
2854+
enum: [draft, completed, deleted]
2855+
default: draft
2856+
25392857

25402858
ScoreLikesCounts:
25412859
type: object

0 commit comments

Comments
 (0)