### Import
- _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
- - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
- - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
+ - _magnet_-based: where the URI resolves to a BitTorrent resource containing a single supported video file
+ - _torrent_-based: where the metainfo file resolves to a BitTorrent resource containing a single supported video file
The import function is practical when the desired video/audio is available online. It makes PeerTube
download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
example: |
**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**
+ '/videos/{id}/source':
+ post:
+ summary: Get video source file metadata
+ operationId: getVideoSource
+ tags:
+ - Video
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoSource'
+
'/videos/{id}/views':
post:
summary: Notify user is watching a video
- 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
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
x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
description: |
If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
- - `quota_reached` for quota limits wether daily or global
+ - `quota_reached` for quota limits whether daily or global
headers:
X-File-Maximum-Size:
schema:
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:
- $ref: '#/components/parameters/name'
- name: withStats
in: query
- description: include view statistics for the last 30 days (only if authentified as the account user)
+ description: include daily view statistics for the last 30 days and total views (only if authentified as the account user)
schema:
type: boolean
- $ref: '#/components/parameters/start'
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:
moderator: Moderator scope
user: User scope
schemas:
- # Resuable core properties
+ # Reusable core properties
id:
type: integer
minimum: 1
- 1
- 2
- 3
- description: 'The live latency mode (Default = `1`, HIght latency = `2`, Small Latency = `3`)'
+ description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)'
VideoStateConstant:
properties:
- 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
$ref: '#/components/schemas/VideoConstantString-Language'
captionPath:
type: string
+ VideoSource:
+ properties:
+ filename:
+ type: string
ActorImage:
properties:
path:
viewersPeakDate:
type: string
format: date-time
- views:
- type: number
- likes:
- type: number
- dislikes:
- type: number
- comments:
- type: number
countries:
type: array
items:
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 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 occurred 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:
'https://search.example.org/api/v1/search/videos':