support/doc/tools.md

   1 # CLI tools guide
   2
   3 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
   4 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
   5 **Table of Contents**
   6
   7 - [Remote Tools](#remote-tools)
   8   - [Dependencies](#dependencies)
   9   - [Installation](#installation)
  10   - [CLI wrapper](#cli-wrapper)
  11     - [peertube-import-videos.js](#peertube-import-videosjs)
  12     - [peertube-upload.js](#peertube-uploadjs)
  13     - [peertube-watch.js](#peertube-watchjs)
  14 - [Server tools](#server-tools)
  15   - [parse-log](#parse-log)
  16   - [create-transcoding-job.js](#create-transcoding-jobjs)
  17   - [create-import-video-file-job.js](#create-import-video-file-jobjs)
  18   - [prune-storage.js](#prune-storagejs)
  19   - [optimize-old-videos.js](#optimize-old-videosjs)
  20   - [update-host.js](#update-hostjs)
  21   - [REPL (Read Eval Print Loop)](#repl-read-eval-print-loop)
  22     - [.help](#help)
  23     - [Lodash example](#lodash-example)
  24     - [YoutubeDL example](#youtubedl-example)
  25     - [Models examples](#models-examples)
  26
  27 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
  28
  29 ## Remote Tools
  30
  31 You need at least 512MB RAM to run the script.
  32 Scripts can be launched directly from a PeerTube server, or from a separate server, even a desktop PC.
  33 You need to follow all the following steps even if you are on a PeerTube server (including cloning the git repository in a different directory than your production installation because the scripts utilize non-production dependencies).
  34
  35 ### Dependencies
  36
  37 Install the [PeerTube dependencies](dependencies.md).
  38
  39 ### Installation
  40
  41 Clone the PeerTube repo to get the latest version (even if you are on your PeerTube server):
  42
  43 ```
  44 $ git clone https://github.com/Chocobozzz/PeerTube.git
  45 $ CLONE="$(pwd)/PeerTube"
  46 ```
  47
  48 Run ``yarn install --pure-lockfile``
  49 ```
  50 $ cd ${CLONE}
  51 $ yarn install --pure-lockfile
  52 ```
  53
  54 Build server tools:
  55 ```
  56 $ cd ${CLONE}
  57 $ npm run build:server
  58 ```
  59
  60 ### CLI wrapper
  61
  62 The wrapper provides a convenient interface to the following scripts. You can access it as `peertube` via an alias in your `.bashrc` like `alias peertube="node /your/peertube/directory/dist/server/tools/peertube.js"`:
  63
  64 ```
  65   Usage: peertube [command] [options]
  66
  67   Options:
  68
  69     -v, --version         output the version number
  70     -h, --help            output usage information
  71
  72   Commands:
  73
  74     auth [action]         register your accounts on remote instances to use them with other commands
  75     upload|up             upload a video
  76     import-videos|import  import a video from a streaming platform
  77     watch|w               watch a video in the terminal ✩°｡⋆
  78     repl                  initiate a REPL to access internals
  79     help [cmd]            display help for [cmd]
  80 ```
  81
  82 The wrapper can keep track of instances you have an account on. We limit to one account per instance for now.
  83
  84 ```bash
  85 $ peertube auth add -u "PEERTUBE_URL" -U "PEERTUBE_USER" --password "PEERTUBE_PASSWORD"
  86 $ peertube auth list
  87 ┌──────────────────────────────┬──────────────────────────────┐
  88 │ instance                     │ login                        │
  89 ├──────────────────────────────┼──────────────────────────────┤
  90 │ "PEERTUBE_URL"               │ "PEERTUBE_USER"              │
  91 └──────────────────────────────┴──────────────────────────────┘
  92 ```
  93
  94 You can now use that account to upload videos without feeding the same parameters again.
  95
  96 ```bash
  97 $ peertube up <videoFile>
  98 ```
  99
 100 And now that your video is online, you can watch it from the confort of your terminal (use `peertube watch --help` to see the supported players):
 101
 102 ```bash
 103 $ peertube watch https://peertube.cpy.re/videos/watch/e8a1af4e-414a-4d58-bfe6-2146eed06d10
 104 ```
 105
 106 #### peertube-import-videos.js
 107
 108 You can use this script to import videos from all [supported sites of youtube-dl](https://rg3.github.io/youtube-dl/supportedsites.html) into PeerTube.
 109 Be sure you own the videos or have the author's authorization to do so.
 110
 111 ```sh
 112 $ node dist/server/tools/peertube-import-videos.js \
 113     -u "PEERTUBE_URL" \
 114     -U "PEERTUBE_USER" \
 115     --password "PEERTUBE_PASSWORD" \
 116     -t "TARGET_URL"
 117 ```
 118
 119 * `PEERTUBE_URL` : the full URL of your PeerTube server where you want to import, eg: https://peertube.cpy.re
 120 * `PEERTUBE_USER` : your PeerTube account where videos will be uploaded
 121 * `PEERTUBE_PASSWORD` : password of your PeerTube account (if omitted, you will be prompted for it)
 122 * `TARGET_URL` : the target url you want to import. Examples:
 123   * YouTube:
 124     * Channel: https://www.youtube.com/channel/ChannelId
 125     * User https://www.youtube.com/c/UserName or https://www.youtube.com/user/UserName
 126     * Video https://www.youtube.com/watch?v=blabla
 127   * Vimeo: https://vimeo.com/xxxxxx
 128   * Dailymotion: https://www.dailymotion.com/xxxxx
 129
 130 The script will get all public videos from Youtube, download them and upload to PeerTube.
 131 Already downloaded videos will not be uploaded twice, so you can run and re-run the script in case of crash, disconnection...
 132
 133 Videos will be publicly available after transcoding (you can see them before that in your account on the web interface).
 134
 135
 136 #### peertube-upload.js
 137
 138 You can use this script to import videos directly from the CLI.
 139
 140 Videos will be publicly available after transcoding (you can see them before that in your account on the web interface).
 141
 142 ```
 143 $ cd ${CLONE}
 144 $ node dist/server/tools/peertube-upload.js --help
 145 ```
 146
 147 #### peertube-watch.js
 148
 149 You can use this script to play videos directly from the CLI.
 150
 151 It provides support for different players:
 152
 153 - ascii (default ; plays in ascii art in your terminal!)
 154 - mpv
 155 - mplayer
 156 - vlc
 157 - stdout
 158 - xbmc
 159 - airplay
 160 - chromecast
 161
 162
 163 ## Server tools
 164
 165 These scripts should be run on the server, in `peertube-latest` directory.
 166
 167 ### parse-log
 168
 169 To parse PeerTube last log file:
 170
 171 ```
 172 $ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run parse-log -- --level info
 173 ```
 174
 175 `--level` is optional and could be `info`/`warn`/`error`
 176
 177 ### create-transcoding-job.js
 178
 179 You can use this script to force transcoding of an existing video. PeerTube needs to be running.
 180
 181 ```
 182 $ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-transcoding-job -- -v [videoUUID]
 183 ```
 184
 185 Or to transcode to a specific resolution:
 186 ```
 187 $ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-transcoding-job -- -v [videoUUID] -r [resolution]
 188 ```
 189
 190 ### create-import-video-file-job.js
 191
 192 You can use this script to import a video file to replace an already uploaded file or to add a new resolution to a video. PeerTube needs to be running.
 193
 194 ```
 195 $ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run create-import-video-file-job -- -v [videoUUID] -i [videoFile]
 196 ```
 197
 198 ### prune-storage.js
 199
 200 Some transcoded videos or shutdown at a bad time can leave some unused files on your storage.
 201 To delete them (a confirmation will be demanded first):
 202
 203 ```
 204 $ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run prune-storage
 205 ```
 206
 207 ### optimize-old-videos.js
 208
 209 Before version v1.0.0-beta.16, Peertube did not specify a bitrate for the
 210 transcoding of uploaded videos. This means that videos might be encoded into
 211 very large files that are too large for streaming. This script re-transcodes
 212 these videos so that they can be watched properly, even on slow connections.
 213
 214 ```
 215 $ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run optimize-old-videos
 216 ```
 217
 218
 219 ### update-host.js
 220
 221 If you started PeerTube with a domain, and then changed it you will have
 222 invalid torrent files and invalid URLs in your database. To fix this, you have
 223 to run:
 224
 225 ```
 226 $ sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run update-host
 227 ```
 228
 229 ### REPL ([Read Eval Print Loop](https://nodejs.org/docs/latest-v8.x/api/repl.html))
 230
 231 If you want to interact with the application libraries and objects even when PeerTube is not running, there is a REPL for that.
 232
 233 usage: `node ./dist/server/tools/peertube-repl.js`
 234
 235 "The default evaluator will, by default, assign the result of the most recently evaluated expression to the special variable `_` (underscore). Explicitly setting `_` to a value will disable this behavior."
 236
 237 - type `.help` to list commands available in the repl, notice it starts with a dot
 238 - type `.exit` to exit, note that you still have to press CTRL-C to actually exit, or press CTRL-C (3 times) without typing `.exit` to exit
 239 - type `context` to list all available objects and libraries in the context, note: `Promise` is also available but it's not listed in the context, in case you need promises for something
 240 - type `env` to see the loaded environment variables
 241 - type `path` to access path library
 242 - type `lodash` to access lodash library
 243 - type `uuidv1` to access uuid/v1 library
 244 - type `uuidv3` to access uuid/v3 library
 245 - type `uuidv4` to access uuid/v4 library
 246 - type `uuidv5` to access uuid/v5 library
 247 - type `YoutubeDL` to access youtube-dl library
 248 - type `cli` to access the cli helpers object
 249 - type `logger` to access the logger; if you log to it, it will write to stdout and to the peertube.log file
 250 - type `constants` to access the constants loaded by the server
 251 - type `coreUtils` to access the core-utils helpers object
 252 - type `ffmpegUtils` to access the ffmpeg-utils helpers object
 253 - type `peertubeCryptoUtils` to access the peertube-crypto helpers object
 254 - type `signupUtils` to access the signup helpers object
 255 - type `utils` to access the utils helpers object
 256 - type `YoutubeDLUtils` to access the youtube-dl helpers object
 257 - type `sequelizeTypescript` to access sequelizeTypescript
 258 - type `modelsUtils` to access the models/utils
 259 - type `models` to access the shortcut to sequelizeTypescript.models
 260 - type `transaction` to access the shortcut to sequelizeTypescript.transaction
 261 - type `query` to access the shortcut to sequelizeTypescript.query
 262 - type `queryInterface` to access the shortcut to sequelizeTypescript.queryInterface
 263
 264 #### .help
 265
 266 ```
 267 PeerTube [1.0.0] (b10eb595)> .help
 268 .break    Sometimes you get stuck, this gets you out
 269 .clear    Break, and also clear the local context
 270 .editor   Enter editor mode
 271 .exit     Exit the repl
 272 .help     Print this help message
 273 .load     Load JS from a file into the REPL session
 274 .r        Reset REPL
 275 .reset    Reset REPL
 276 .save     Save all evaluated commands in this REPL session to a file
 277 PeerTube [1.0.0] (b10eb595)>
 278 ```
 279
 280 #### Lodash example
 281
 282 ```
 283 PeerTube [1.0.0] (b10eb595)> lodash.keys(context)
 284 [ 'global',
 285   'console',
 286   'DTRACE_NET_SERVER_CONNECTION',
 287   'DTRACE_NET_STREAM_END',
 288   'DTRACE_HTTP_SERVER_REQUEST',
 289   'DTRACE_HTTP_SERVER_RESPONSE',
 290   'DTRACE_HTTP_CLIENT_REQUEST',
 291   'DTRACE_HTTP_CLIENT_RESPONSE',
 292   'process',
 293   'Buffer',
 294   'clearImmediate',
 295   'clearInterval',
 296   'clearTimeout',
 297   'setImmediate',
 298   'setInterval',
 299   'setTimeout',
 300   'XMLHttpRequest',
 301   'compact2string',
 302   'module',
 303   'require',
 304   'path',
 305   'repl',
 306   'context',
 307   'env',
 308   'lodash',
 309   'uuidv1',
 310   'uuidv3',
 311   'uuidv4',
 312   'uuidv5',
 313   'cli',
 314   'logger',
 315   'constants',
 316   'Sequelize',
 317   'sequelizeTypescript',
 318   'modelsUtils',
 319   'models',
 320   'transaction',
 321   'query',
 322   'queryInterface',
 323   'YoutubeDL',
 324   'coreUtils',
 325   'ffmpegUtils',
 326   'peertubeCryptoUtils',
 327   'signupUtils',
 328   'utils',
 329   'YoutubeDLUtils' ]
 330 PeerTube [1.0.0] (b10eb595)>
 331 ```
 332
 333 #### YoutubeDL example
 334 ```
 335 YoutubeDL.getInfo('https://www.youtube.com/watch?v=I5ZN289jjDo', function(err, data) {console.log(err, data)})
 336 ```
 337
 338 #### Models examples
 339 ```
 340 PeerTube [1.0.0] (b10eb595)> new models.ActorModel({id: 3}).getVideoChannel().then(function(data){console.log(data.dataValues.name)})
 341 Promise {
 342   _bitField: 0,
 343   _fulfillmentHandler0: undefined,
 344   _rejectionHandler0: undefined,
 345   _promise0: undefined,
 346   _receiver0: undefined }
 347 PeerTube [1.0.0] (b10eb595)> Main root channel
 348 PeerTube [1.0.0] (b10eb595)> let out; new models.UserModel({id: 1}).getAccount().then(function (data) {out = data.dataValues.id})
 349 Promise {
 350   _bitField: 0,
 351   _fulfillmentHandler0: undefined,
 352   _rejectionHandler0: undefined,
 353   _promise0: undefined,
 354   _receiver0: undefined }
 355 PeerTube [1.0.0] (b10eb595)> out
 356 2
 357 PeerTube [1.0.0] (b10eb595)>
 358 ```