davidl/MyTube
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update doc

Browse Source
This commit is contained in:
Peifan Li
2026-01-04 17:08:53 -05:00
parent 79530dbca2
commit a4eaaa3180
12 changed files with 423 additions and 689 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
documents/en/hooks-guide.md
View File

@@ -1,44 +1,43 @@
# Task Hooks Guide
MyTube allows you to execute custom shell scripts at various stages of a download task's lifecycle. This feature is powerful for integrating MyTube with other systems, performing post-processing on downloaded files, or sending notifications.
MyTube lets you execute custom shell scripts at different stages of a download task. This is useful for post-processing, notifications, or external integrations.
## available Hooks
You can configure commands for the following events:
## Available Hooks
| Hook Name | Trigger Point | Description |
| :--- | :--- | :--- |
| **Before Task Start** (`task_before_start`) | Before download begins | Executed immediately before the download process starts. Useful for setup or validation. |
| **Task Success** (`task_success`) | After successful download | Executed after the file is successfully downloaded / merged, but **before** it is uploaded to cloud storage (if enabled) or deleted. This is the ideal place for file processing. |
| **Task Failed** (`task_fail`) | On task failure | Executed if the download fails for any reason. |
| **Task Cancelled** (`task_cancel`) | On task cancellation | Executed when a user manually cancels a running task. |
| **Before Task Start** (`task_before_start`) | Before download begins | Runs right before the download starts. |
| **Task Success** (`task_success`) | After successful download | Runs after download/merge completes but **before** cloud upload (if enabled) or deletion. |
| **Task Failed** (`task_fail`) | On task failure | Runs when a download fails. |
| **Task Cancelled** (`task_cancel`) | On task cancellation | Runs when a user cancels a running task. |
Hook scripts are stored under `backend/data/hooks` by default.
## Environment Variables
When a hook command is executed, the following environment variables are injected into the shell environment, providing context about the task:
| Variable | Description | Example |
| :--- | :--- | :--- |
| `MYTUBE_TASK_ID` | The unique identifier of the task | `335e98f0-15cb-46a4-846d-9d4351368923` |
| `MYTUBE_TASK_TITLE` | The title of the video/task | `Awesome Video Title` |
| `MYTUBE_SOURCE_URL` | The original URL of the video | `https://www.youtube.com/watch?v=...` |
| `MYTUBE_TASK_STATUS` | The current status of the task | `success`, `fail`, `cancelled` |
| `MYTUBE_VIDEO_PATH` | Absolute path to the downloaded video file | `/app/downloads/video.mp4` |
| `MYTUBE_THUMBNAIL_PATH` | Absolute path to the thumbnail file | `/app/downloads/video.jpg` |
| `MYTUBE_TASK_ID` | Unique task ID | `335e98f0-15cb-46a4-846d-9d4351368923` |
| `MYTUBE_TASK_TITLE` | Video/task title | `Awesome Video Title` |
| `MYTUBE_SOURCE_URL` | Original video URL | `https://www.youtube.com/watch?v=...` |
| `MYTUBE_TASK_STATUS` | Current status | `start`, `success`, `fail`, `cancel` |
| `MYTUBE_VIDEO_PATH` | Absolute path to video file | `/app/uploads/videos/video.mp4` |
| `MYTUBE_THUMBNAIL_PATH` | Absolute path to thumbnail | `/app/uploads/images/video.jpg` |
| `MYTUBE_ERROR` | Error message (only for `task_fail`) | `Network timeout` |
## Configuration
You can configure hooks in the web interface:
1. Go to **Settings**.
2. Scroll down to **Advanced Settings**.
3. Find the **Task Hooks** section.
4. Upload your `.sh` scripts for the desired events.
5. You can Delete or Re-upload scripts as needed.
2. Open **Advanced Settings**.
3. Find **Task Hooks**.
4. Upload `.sh` scripts for the desired events.
5. Delete or re-upload as needed.
Hooks are executed with `bash` and are made executable on upload.
## Viewing Logs
Any output from your script (stdout/stderr) will be captured and logged to the MyTube server console.
Any output from your script (stdout/stderr) is captured and logged by the backend.
- Standard output (`echo "..."`) is logged as `INFO`.
- Standard error (`>&2 echo "..."`) is logged as `WARN`.
@@ -69,7 +68,7 @@ curl -d "MyTube Download Failed: $MYTUBE_TASK_TITLE - $MYTUBE_ERROR" https://ntf
```
### 3. File Post-Processing
Run a python script to process the file.
Run a Python script to process the file.
**Hook:** `task_success`
```bash
#!/bin/bash
@@ -79,7 +78,7 @@ python3 /path/to/process_video.py "$MYTUBE_VIDEO_PATH"
## Security Warning
> [!WARNING]
> Hook commands are executed with the same permissions as the MyTube backend server.
> Hook commands run with the same permissions as the MyTube backend.
> - Be careful when using commands that modify or delete files.
> - Do not copy-paste scripts from untrusted sources.
> - Do not copy/paste scripts from untrusted sources.
> - Ensure your scripts handle errors gracefully.