mirror of
https://github.com/wukko/cobalt.git
synced 2025-06-12 21:27:39 +02:00
updated docs
This commit is contained in:
wukko
128
docs/API.md
128
docs/API.md
@ -1,73 +1,79 @@
|
||||
# cobalt API Documentation
|
||||
This document provides info about methods and acceptable variables for all cobalt API requests.<br>
|
||||
# cobalt api documentation
|
||||
this document provides info about methods and acceptable variables for all cobalt api requests.
|
||||
|
||||
```
|
||||
⚠️ Main API instance has moved to https://co.wuk.sh/
|
||||
|
||||
Make sure your projects use the correct API domain.
|
||||
👍 you can use co.wuk.sh instance in your projects for free, just don't be an asshole.
|
||||
```
|
||||
|
||||
## POST: ``/api/json``
|
||||
Main processing endpoint.<br>
|
||||
## POST: `/api/json`
|
||||
cobalt's main processing endpoint.
|
||||
|
||||
Request Body Type: ``application/json``<br>
|
||||
Response Body Type: ``application/json``
|
||||
request body type: `application/json`
|
||||
response body type: `application/json`
|
||||
|
||||
### Request Body Variables
|
||||
| key | type | variables | default | description |
|
||||
|:--------------------|:------------|:-------------------------------------|:------------|:-------------------------------------------------------------------------------|
|
||||
| ``url`` | ``string`` | Sharable URL encoded as URI | ``null`` | **Must** be included in every request. |
|
||||
| ``vCodec`` | ``string`` | ``h264 / av1 / vp9`` | ``h264`` | Applies only to YouTube downloads. ``h264`` is recommended for phones. |
|
||||
| ``vQuality`` | ``string`` | ``144 / ... / 2160 / max`` | ``720`` | ``720`` quality is recommended for phones. |
|
||||
| ``aFormat`` | ``string`` | ``best / mp3 / ogg / wav / opus`` | ``mp3`` | |
|
||||
| ``filenamePattern`` | ``boolean`` | ``classic / pretty / basic / nerdy`` | ``classic`` | Changes the way files are named. Previews can be seen in the web app. |
|
||||
| ``isAudioOnly`` | ``boolean`` | ``true / false`` | ``false`` | |
|
||||
| ``isNoTTWatermark`` | ``boolean`` | ``true / false`` | ``false`` | Changes whether downloaded TikTok videos have watermarks. |
|
||||
| ``isTTFullAudio`` | ``boolean`` | ``true / false`` | ``false`` | Enables download of original sound used in a TikTok video. |
|
||||
| ``isAudioMuted`` | ``boolean`` | ``true / false`` | ``false`` | Disables audio track in video downloads. |
|
||||
| ``dubLang`` | ``boolean`` | ``true / false`` | ``false`` | Backend uses Accept-Language for YouTube video audio tracks when ``true``. |
|
||||
| ``disableMetadata`` | ``boolean`` | ``true / false`` | ``false`` | Disables file metadata when set to ``true``. |
|
||||
```
|
||||
⚠️ you must include Accept and Content-Type headers with every POST /api/json request.
|
||||
|
||||
### Response Body Variables
|
||||
| key | type | variables |
|
||||
|:---------------|:-----------|:--------------------------------------------------------------|
|
||||
| ``status`` | ``string`` | ``error / redirect / stream / success / rate-limit / picker`` |
|
||||
| ``text`` | ``string`` | Text |
|
||||
| ``url`` | ``string`` | Direct link to a file / link to cobalt's live render |
|
||||
| ``pickerType`` | ``string`` | ``various / images`` |
|
||||
| ``picker`` | ``array`` | Array of picker items |
|
||||
| ``audio`` | ``string`` | Direct link to a file / link to cobalt's live render |
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
### Picker Item Variables
|
||||
Item type: ``object``
|
||||
| key | type | variables | description |
|
||||
|:---------------|:-----------|:------------------------------------------------|:--------------------------------------------|
|
||||
| ``type`` | ``string`` | ``video`` | Used only if ``pickerType`` is ``various``. |
|
||||
| ``url`` | ``string`` | Direct link to a file / link to cobalt's live render | |
|
||||
| ``thumb`` | ``string`` | Item thumbnail that's displayed in the picker | Used only for ``video`` type. |
|
||||
### request body variables
|
||||
| key | type | variables | default | description |
|
||||
|:------------------|:----------|:-----------------------------------|:----------|:-------------------------------------------------------------------------------|
|
||||
| `url` | `string` | URL encoded as URI | `null` | **must** be included in every request. |
|
||||
| `vCodec` | `string` | `h264 / av1 / vp9` | `h264` | applies only to youtube downloads. `h264` is recommended for phones. |
|
||||
| `vQuality` | `string` | `144 / ... / 2160 / max` | `720` | `720` quality is recommended for phones. |
|
||||
| `aFormat` | `string` | `best / mp3 / ogg / wav / opus` | `mp3` | |
|
||||
| `filenamePattern` | `boolean` | `classic / pretty / basic / nerdy` | `classic` | changes the way files are named. previews can be seen in the web app. |
|
||||
| `isAudioOnly` | `boolean` | `true / false` | `false` | |
|
||||
| `isNoTTWatermark` | `boolean` | `true / false` | `false` | changes whether downloaded tiktok videos have watermarks. |
|
||||
| `isTTFullAudio` | `boolean` | `true / false` | `false` | enables download of original sound used in a tiktok video. |
|
||||
| `isAudioMuted` | `boolean` | `true / false` | `false` | disables audio track in video downloads. |
|
||||
| `dubLang` | `boolean` | `true / false` | `false` | backend uses Accept-Language hader for youtube video audio tracks when `true`. |
|
||||
| `disableMetadata` | `boolean` | `true / false` | `false` | disables file metadata when set to `true`. |
|
||||
|
||||
## GET: ``/api/stream``
|
||||
Content live render streaming endpoint.<br>
|
||||
### response body variables
|
||||
| key | type | variables |
|
||||
|:-------------|:---------|:------------------------------------------------------------|
|
||||
| `status` | `string` | `error / redirect / stream / success / rate-limit / picker` |
|
||||
| `text` | `string` | various text, mostly used for errors |
|
||||
| `url` | `string` | direct link to a file or a link to cobalt's live render |
|
||||
| `pickerType` | `string` | `various / images` |
|
||||
| `picker` | `array` | array of picker items |
|
||||
| `audio` | `string` | direct link to a file or a link to cobalt's live render |
|
||||
|
||||
### Request Query Variables
|
||||
| key | variables | description |
|
||||
|:--------|:-----------------|:-------------------------------------------------------------------------------------------------------------------------------|
|
||||
| ``p`` | ``1`` | Used for probing whether user is rate limited. |
|
||||
| ``t`` | Stream token | Unique stream ID. Used for retrieving cached stream info data. |
|
||||
| ``h`` | HMAC | Hashed combination of: (hashed) ip address, stream token, expiry timestamp, and service name. Used for verification of stream. |
|
||||
| ``e`` | Expiry timestamp | |
|
||||
### picker item variables
|
||||
item type: `object`
|
||||
|
||||
## GET: ``/api/serverInfo``
|
||||
Returns current basic server info.<br>
|
||||
Response Body Type: ``application/json``
|
||||
| key | type | variables | description |
|
||||
|:--------|:---------|:--------------------------------------------------------|:---------------------------------------|
|
||||
| `type` | `string` | `video` | used only if `pickerType`is `various`. |
|
||||
| `url` | `string` | direct link to a file or a link to cobalt's live render | |
|
||||
| `thumb` | `string` | item thumbnail that's displayed in the picker | used only for `video` type. |
|
||||
|
||||
### Response Body Variables
|
||||
| key | type | variables |
|
||||
|:--------------|:-----------|:------------------|
|
||||
| ``version`` | ``string`` | cobalt version |
|
||||
| ``commit`` | ``string`` | Git commit |
|
||||
| ``branch`` | ``string`` | Git branch |
|
||||
| ``name`` | ``string`` | Server name |
|
||||
| ``url`` | ``string`` | Server url |
|
||||
| ``cors`` | ``int`` | CORS status |
|
||||
| ``startTime`` | ``string`` | Server start time |
|
||||
## GET: `/api/stream`
|
||||
cobalt's live render (or stream) endpoint. used for sending various media content over to the user.
|
||||
|
||||
### request query variables
|
||||
| key | variables | description |
|
||||
|:-----|:-----------------|:-------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `p` | `1` | used for probing whether user is rate limited. |
|
||||
| `t` | stream token | unique stream id. used for retrieving cached stream info data. |
|
||||
| `h` | hmac | hashed combination of: (hashed) ip address, stream token, expiry timestamp, and service name. used for verification of stream. |
|
||||
| `e` | expiry timestamp | |
|
||||
|
||||
## GET: `/api/serverInfo`
|
||||
returns current basic server info.
|
||||
response body type: `application/json`
|
||||
|
||||
### response body variables
|
||||
| key | type | variables |
|
||||
|:------------|:---------|:------------------|
|
||||
| `version` | `string` | cobalt version |
|
||||
| `commit` | `string` | git commit |
|
||||
| `branch` | `string` | git branch |
|
||||
| `name` | `string` | server name |
|
||||
| `url` | `string` | server url |
|
||||
| `cors` | `int` | cors status |
|
||||
| `startTime` | `string` | server start time |
|
||||
|
||||
5
docs/examples/cookies.example.json
Normal file
5
docs/examples/cookies.example.json
Normal file
@ -0,0 +1,5 @@
|
||||
{
|
||||
"instagram": [
|
||||
"mid=replace; ig_did=this; csrftoken=cookie"
|
||||
]
|
||||
}
|
||||
66
docs/examples/docker-compose.example.yml
Normal file
66
docs/examples/docker-compose.example.yml
Normal file
@ -0,0 +1,66 @@
|
||||
version: '3.5'
|
||||
|
||||
services:
|
||||
cobalt-api:
|
||||
image: ghcr.io/wukko/cobalt:latest
|
||||
restart: unless-stopped
|
||||
container_name: cobalt-api
|
||||
|
||||
init: true
|
||||
|
||||
# if container doesn't run detached on your machine, uncomment the next line:
|
||||
#tty: true
|
||||
|
||||
ports:
|
||||
- 9000:9000/tcp
|
||||
# if you're using a reverse proxy, uncomment the next line:
|
||||
#- 127.0.0.1:9000:9000
|
||||
|
||||
environment:
|
||||
- apiPort=9000
|
||||
# replace apiURL with your instance's target url in same format
|
||||
- apiURL=https://co.wuk.sh/
|
||||
# replace apiName with your instance's distinctive name
|
||||
- apiName=eu-nl
|
||||
# if you want to use cookies when fetching data from services, uncomment the next line
|
||||
#- cookiePath=/cookies.json
|
||||
# see cookies_example.json for example file.
|
||||
labels:
|
||||
- com.centurylinklabs.watchtower.scope=cobalt
|
||||
|
||||
# if you want to use cookies when fetching data from services, uncomment volumes and next line
|
||||
#volumes:
|
||||
#- ./cookies.json:/cookies.json
|
||||
|
||||
cobalt-web:
|
||||
image: ghcr.io/wukko/cobalt:latest
|
||||
restart: unless-stopped
|
||||
container_name: cobalt-web
|
||||
|
||||
init: true
|
||||
|
||||
# if container doesn't run detached on your machine, uncomment the next line:
|
||||
#tty: true
|
||||
|
||||
ports:
|
||||
- 9001:9001/tcp
|
||||
# if you're using a reverse proxy, uncomment the next line:
|
||||
#- 127.0.0.1:9001:9001
|
||||
|
||||
environment:
|
||||
- webPort=9001
|
||||
# replace webURL with your instance's target url in same format
|
||||
- webURL=https://cobalt.tools/
|
||||
# replace apiURL with preferred api instance url
|
||||
- apiURL=https://co.wuk.sh/
|
||||
|
||||
labels:
|
||||
- com.centurylinklabs.watchtower.scope=cobalt
|
||||
|
||||
# update the cobalt image automatically with watchtower
|
||||
watchtower:
|
||||
image: ghcr.io/containrrr/watchtower
|
||||
restart: unless-stopped
|
||||
command: --cleanup --scope cobalt --interval 900
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
44
docs/run-an-instance.md
Normal file
44
docs/run-an-instance.md
Normal file
@ -0,0 +1,44 @@
|
||||
# how to host a cobalt instance yourself
|
||||
## using docker compose and package from github (recommended)
|
||||
to run the cobalt docker package, you need to have `docker` and `docker-compose` installed and configured.
|
||||
|
||||
if you need help with installing docker, follow *only the first step* of these tutorials by digitalocean:
|
||||
- [how to install docker](https://www.digitalocean.com/community/tutorial-collections/how-to-install-and-use-docker)
|
||||
- [how to install docker compose](https://www.digitalocean.com/community/tutorial-collections/how-to-install-docker-compose)
|
||||
|
||||
## how to run a cobalt docker package:
|
||||
1. create a folder for cobalt config file, something like this:
|
||||
```sh
|
||||
mkdir cobalt
|
||||
```
|
||||
|
||||
2. go to cobalt folder, and create a docker compose config file:
|
||||
```sh
|
||||
cd cobalt && nano docker-compose.yml
|
||||
```
|
||||
i'm using `nano` in this example, it may not be available in your distro. you can use any other text editor.
|
||||
|
||||
3. copy and paste the [sample config from here](https://github.com/wukko/cobalt/blob/current/docs/examples/docker-compose.example.json) for either web or api instance (or both, if you wish) and edit it to your needs.
|
||||
make sure to replace default URLs with yours or cobalt won't work correctly.
|
||||
|
||||
if you want your instance to support services that require authentication to view public content, create `cookies.json` file in the same directory as `docker-compose.yml`. example file for cookies file [can be found here](https://github.com/wukko/cobalt/blob/current/docs/examples/cookies.example.json).
|
||||
|
||||
cobalt package will automatically update itself thanks to watchtower.
|
||||
|
||||
it's highly recommended to use a reverse proxy (such as nginx) if you want your instance to face the public internet. look up tutorials for that online.
|
||||
|
||||
## using regular node.js (useful for local development)
|
||||
setup script installs all needed `npm` dependencies, but you have to install `node.js` *(version 18 or above)* and `git` yourself.
|
||||
|
||||
1. clone the repo: `git clone https://github.com/wukko/cobalt`.
|
||||
2. run setup script and follow instructions: `npm run setup`. you need to host api and web instances separately, so pick whichever applies.
|
||||
3. run cobalt via `npm start`.
|
||||
4. done.
|
||||
|
||||
### ubuntu 22.04 workaround
|
||||
`nscd` needs to be installed and running so that the `ffmpeg-static` binary can resolve DNS ([#101](https://github.com/wukko/cobalt/issues/101#issuecomment-1494822258)):
|
||||
|
||||
```bash
|
||||
sudo apt install nscd
|
||||
sudo service nscd start
|
||||
```
|
||||
33
docs/troubleshooting.md
Normal file
33
docs/troubleshooting.md
Normal file
@ -0,0 +1,33 @@
|
||||
# self-troubleshooting cobalt
|
||||
```
|
||||
🚧 this page is work-in-progress. expect more guides to be added in the future!
|
||||
```
|
||||
if any issues occur while using cobalt, you can fix many of them yourself. this document aims to provide guides on how to fix most complicated of them.
|
||||
use wiki navigation on right to jump between solutions.
|
||||
|
||||
## how to fix clipboard pasting in firefox
|
||||
you can fix this issue by changing a single preference in `about:config`.
|
||||
|
||||
### steps to enable clipboard functionality
|
||||
1. go to `about:config`:
|
||||
|
||||
|
||||
|
||||
2. if asked, read what firefox has to say and press "accept the risk and continue".
|
||||
⚠ tinkering with other preferences may break your browser. **do not** edit them unless you know what you're doing.
|
||||
|
||||
|
||||
|
||||
3. search for `dom.events.asyncclipboard.readtext`
|
||||
|
||||
|
||||
|
||||
4. press the toggle button on very right.
|
||||
|
||||
|
||||
|
||||
5. "false" should change to "true".
|
||||
|
||||
|
||||
|
||||
6. go back to cobalt, reload the page, press `paste and download` button again. this time it works! enjoy simpler downloading experience :)
|
||||
Reference in New Issue
Block a user