description: Operations on video files
- name: Video Transcoding
description: Video transcoding related operations
+ - name: Video stats
+ description: Video statistics
- name: Feeds
description: Server syndication feeds
- name: Search
- Video Comments
- Video Rates
- Video Playlists
+ - Video Stats
- Video Ownership Change
- Video Mirroring
- Video Files
'/videos/{id}/views':
post:
- summary: Add a view to a video
+ summary: Notify user is watching a video
+ description: Call this endpoint regularly (every 5-10 seconds for example) to notify the server the user is watching the video. After a while, PeerTube will increase video's viewers counter. If the user is authenticated, PeerTube will also store the current player time.
operationId: addView
tags:
- Video
parameters:
- $ref: '#/components/parameters/idOrUUID'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UserViewingVideo'
+ required: true
responses:
'204':
description: successful operation
'/videos/{id}/watching':
put:
summary: Set watching progress of a video
- operationId: setProgress
+ deprecated: true
+ description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
tags:
- Video
security:
content:
application/json:
schema:
- $ref: '#/components/schemas/UserWatchingVideo'
+ $ref: '#/components/schemas/UserViewingVideo'
required: true
responses:
'204':
description: successful operation
+ '/videos/{id}/stats/overall':
+ get:
+ summary: Get overall stats of a video
+ tags:
+ - Video Stats
+ security:
+ - OAuth2: []
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ - name: startDate
+ in: query
+ description: Filter stats by start date
+ schema:
+ type: string
+ format: date-time
+ - name: endDate
+ in: query
+ description: Filter stats by end date
+ schema:
+ type: string
+ format: date-time
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoStatsOverall'
+
+ '/videos/{id}/stats/retention':
+ get:
+ summary: Get retention stats of a video
+ tags:
+ - Video Stats
+ security:
+ - OAuth2: []
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoStatsRetention'
+
+ '/videos/{id}/stats/timeseries/{metric}':
+ get:
+ summary: Get timeserie stats of a video
+ tags:
+ - Video Stats
+ security:
+ - OAuth2: []
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ -
+ name: metric
+ in: path
+ required: true
+ description: The metric to get
+ schema:
+ type: string
+ enum:
+ - 'viewers'
+ - 'aggregateWatchTime'
+ - name: startDate
+ in: query
+ description: Filter stats by start date
+ schema:
+ type: string
+ format: date-time
+ - name: endDate
+ in: query
+ description: Filter stats by end date
+ schema:
+ type: string
+ format: date-time
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoStatsTimeserie'
+
/videos/upload:
post:
summary: Upload a video
in: query
required: true
description: |
- Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
+ Created session id to proceed with. If you didn't send chunks in the last hour, it is
not valid anymore and you need to initialize a new upload.
schema:
type: string
description: |
Size of the chunk that the request is sending.
- The chunk size __must be a multiple of 256 KB__, and unlike [Google Resumable](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol)
- doesn't mandate for chunks to have the same size throughout the upload sequence.
-
Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1048576 bytes (~1MB) and increases or reduces size depending on connection health.
requestBody:
permanentLive:
description: User can stream multiple times in a permanent live
type: boolean
+ latencyMode:
+ description: User can select live latency mode if enabled by the instance
+ $ref: '#/components/schemas/LiveVideoLatencyMode'
thumbnailfile:
description: Live video/replay thumbnail file
type: string
description: bad parameters or trying to update a live that has already started
'403':
description: trying to save replay of the live but saving replay is not enabled on the instance
+ /videos/live/{id}/sessions:
+ get:
+ summary: List live sessions
+ description: List all sessions created in a particular live
+ security:
+ - OAuth2: []
+ tags:
+ - Live Videos
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/LiveVideoSessionResponse'
+ /videos/{id}/live-session:
+ get:
+ summary: Get live session of a replay
+ description: If the video is a replay of a live, you can find the associated live session using this endpoint
+ security:
+ - OAuth2: []
+ tags:
+ - Live Videos
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LiveVideoSessionResponse'
/users/me/abuses:
get:
name: sort
in: query
required: false
- description: Sort videos by criteria
schema:
type: string
enum:
- - name
- - -duration
- - -createdAt
- - -publishedAt
- - -views
- - -likes
- - -trending
- - -hot
+ - name
+ - -duration
+ - -createdAt
+ - -publishedAt
+ - -views
+ - -likes
+ - -trending
+ - -hot
+ - -best
+ description: >
+ Sort videos by criteria (prefixing with `-` means `DESC` order):
+ * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
+ * `best` - Same than `hot`, but also takes into account user video history
+ * `trending` - Sort videos by recent views ("recent" is defined by the admin)
+ * `views` - Sort videos using their `views` counter
+ * `publishedAt` - Sort by video publication date (when it became publicly available)
videosSearchSort:
name: sort
in: query
required: false
- description: Sort videos by criteria
+ description: >
+ Sort videos by criteria (prefixing with `-` means `DESC` order):
schema:
type: string
enum:
description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
example: 1
+ LiveVideoLatencyMode:
+ type: integer
+ enum:
+ - 1
+ - 2
+ - 3
+ description: 'The live latency mode (Default = `1`, HIght latency = `2`, Small Latency = `3`)'
+
VideoStateConstant:
properties:
id:
- 1
- 2
- 3
- description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
+ - 4
+ - 5
+ - 6
+ - 7
+ - 8
+ - 9
+ description: |
+ The video state:
+ - `1`: Published
+ - `2`: To transcode
+ - `3`: To import
+ - `4`: Waiting for live stream
+ - `5`: Live ended
+ - `6`: To move to an external storage (object storage...)
+ - `7`: Transcoding failed
+ - `8`: Moving to an external storage failed
+ - `9`: To edit using studio edition feature
label:
type: string
description:
type: string
description: text or bio displayed on the account's profile
- UserWatchingVideo:
+ UserViewingVideo:
+ required:
+ - currentTime
properties:
currentTime:
type: integer
format: seconds
description: timestamp within the video, in seconds
example: 5
+ viewEvent:
+ type: string
+ enum:
+ - seek
+ description: >
+ Event since last viewing call:
+ * `seek` - If the user seeked the video
+
+ VideoStatsOverall:
+ properties:
+ averageWatchTime:
+ type: number
+ totalWatchTime:
+ type: number
+ viewersPeak:
+ type: number
+ viewersPeakDate:
+ type: string
+ format: date-time
+ countries:
+ type: array
+ items:
+ type: object
+ properties:
+ isoCode:
+ type: string
+ viewers:
+ type: number
+
+ VideoStatsRetention:
+ properties:
+ data:
+ type: array
+ items:
+ type: object
+ properties:
+ second:
+ type: number
+ retentionPercent:
+ type: number
+
+ VideoStatsTimeserie:
+ properties:
+ data:
+ type: array
+ items:
+ type: object
+ properties:
+ date:
+ type: string
+ value:
+ type: number
+
ServerConfig:
properties:
instance:
permanentLive:
description: User can stream multiple times in a permanent live
type: boolean
+ latencyMode:
+ description: User can select live latency mode if enabled by the instance
+ $ref: '#/components/schemas/LiveVideoLatencyMode'
LiveVideoResponse:
properties:
rtmpUrl:
type: string
+ description: Included in the response if an appropriate token is provided
rtmpsUrl:
type: string
+ description: Included in the response if an appropriate token is provided
streamKey:
type: string
- description: RTMP stream key to use to stream into this live video
+ description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
saveReplay:
type: boolean
permanentLive:
description: User can stream multiple times in a permanent live
type: boolean
+ latencyMode:
+ description: User can select live latency mode if enabled by the instance
+ $ref: '#/components/schemas/LiveVideoLatencyMode'
-
+ LiveVideoSessionResponse:
+ properties:
+ id:
+ type: integer
+ startDate:
+ type: string
+ format: date-time
+ description: Start date of the live session
+ endDate:
+ type: string
+ format: date-time
+ nullable: true
+ description: End date of the live session
+ error:
+ type: integer
+ enum:
+ - 1
+ - 2
+ - 3
+ - 4
+ - 5
+ nullable: true
+ description: >
+ Error type if an error occured during the live session:
+ - `1`: Bad socket health (transcoding is too slow)
+ - `2`: Max duration exceeded
+ - `3`: Quota exceeded
+ - `4`: Quota FFmpeg error
+ - `5`: Video has been blacklisted during the live
+ replayVideo:
+ type: object
+ description: Video replay information
+ properties:
+ id:
+ type: number
+ uuid:
+ $ref: '#/components/schemas/UUIDv4'
+ shortUUID:
+ $ref: '#/components/schemas/shortUUID'
callbacks:
searchIndex:
projects / github / Chocobozzz / PeerTube.git / blobdiff