clips2share 0.0.20b2
Helper for creating adult torrents
Requires Python: >=3.11
Keywords: torrent, clips4sale, thumbnail

# clips2share

Clips2share helps you with the process of creating torrents for uploading adult clips to your favorite torrent tracker:

- clipstore plugin system currently supporting:
  - Clips4Sale
  - iWantclips (experimental beta support using cloudscraper or manual HTML input)
  - ManyVids
  - (new plugins can be easily added by placing the plugin in clips2share/clipstores/your_store.py)
- extract all metadata from a user provided clipstore link (title, description, tags, price, clip quality, and more)
- embed all these data using a template in the torrents metadata
- download header image from clipstore and upload to an image hoster 
- create thumbnails from local clip using vcsi library and upload to image hoster 
- create the final torrent with torf lib and send it to qbittorrent 
- allows uploading to multiple trackers


## Installation

There are currently 4 different ways of running clips2share, based on the OS you are using:

| OS       | Binary | PyPI / PIP | Docker | source |
|----------|--------|------------|--------|--------|
| Windows  | ❌     | ✅          | ✅     | ✅     |
| Mac OS X | ❌     | ✅          | ✅     | ✅     |
| Linux    | ✅     | ✅          | ✅     | ✅     | 

### Binary

Download, unpack and run the latest binary from the [release page](https://codeberg.org/c2s/clips2share/releases) and make sure that [ffmpeg](https://ffmpeg.org/) is installed in your PATH.

### PyPI / PIP

If python with PIP is already installed, just run `pip install clips2share` and make sure that [ffmpeg](https://ffmpeg.org/) is installed in your PATH.

### Docker

You can run clips2share without installing it locally using Docker:

```bash
docker run --pull always --rm --user $(id -u):$(id -g) \
  -v /mypath/config:/config \
  -v /mypath/torrent:/torrent \
  noired4/clips2share:latest \
  --video "/torrent/Upload/video.mp4" \
  --url "https://www.example.com" \
  --delay-seconds 120
```
This runs the app in a temporary container, mounts your configuration and video folders, and passes the necessary arguments. The container will automatically remove itself when the task is complete.

#### Notes
- The '/config' volume should contain a config.toml file. You can use the example provided in the Configuration section.
- The '/data' volume should point to a directory containing the video file you want to upload.
- If you use qBittorrent with watch folders, ensure that the 'qbittorrent_watch_dir' path in config.toml is mapped inside '/data' so the generated .torrent file appears in the expected location inside the container.
- **Important:** Make sure that the path mappings used by your qBittorrent container match those used by clips2share. For example, if both containers access your host's '/home/user/data' as '/data', the paths will align correctly. If they don’t match, torrent files may reference incorrect locations, causing qBittorrent to fail seeding.
- **Also important:** The 'torrent_temp_dir' setting must point to a directory that exists inside a Docker-mounted volume. This ensures that the resulting .torrent file is accessible on your host system, allowing you to upload it to a tracker or inspect it if needed.


## Configuration

This is an example config.toml

```toml
[client.qbittorrent]
# Location where destination files are created
upload_directory = '/home/user/uploads/'

# Watch location where final torrents will be copied to for automatic seeding
# (If use_api is set to true, watch_directory will be ignored)
watch_directory = '/home/user/uploads/_autoadd/'

# API Settings
use_api = false
url = 'http://user:pass@127.0.0.1:8080'
category = 'Upload'

# Wait either for user input or --delay-seconds [seconds] to delay seed after torrent creation to prevent announcing an unknown torrent to tracker
delayed_seed = true

[image_host.chevereto]
# Host and API Credentials of a chevereto image hosting instance used for uploading header and thumbnail images
host = 'hamster.is'
api_key = 'chv_your_api_key_check_your_user_settings_after_logging_in'

[torrent]
# Tags to decorate tracker uploads
static_tags = ['clips4sale.com']
# Sets the torrent description template. If left blank, the default BBCode template is used.
template = 'default_bbcode.jinja'
# Location for torrents ready to be uploaded to a tracker
temporary_directory = '/home/user/temp/'
# If use_hardlinks set to true, torrent sources will use filesystem hardlinks instead of symlimks.
# This can prevent accidental deletion of files. Set this to false if source files come from other/remote filesystems.
use_hardlinks = true

# Tracker Sections
# Add one or more trackers here

[[trackers]]
name = 'opentrackr'
announce_url = 'udp://tracker.opentrackr.org:1337/announce'
source_tag = 'opentrackr'
category = 'none'

[[trackers]]
name = 'empornium'
announce_url = 'http://tracker.empornium.sx:2710/YOURPASSKEY/announce'
source_tag = 'Emp'
category = 'Straight'
```


| Client (QBittorrent) | Description                                                                                     |
|----------------------|-------------------------------------------------------------------------------------------------|
| upload_directory     | Directory where the upload files are created                                                    |
| watch_directory      | Directory where the torrent is moved to get automatically seeded                                |
| use_api              | If true, uses client API instead of watch folders                                               |
| url                  | API URL for uploading a Torrent via API including username, password and port                   |
| category             | API Category for the new torrent within Qbittorrent                                             |
| delayed_seed         | If true, wait for user input and delay seed to prevent announcing an unknown torrent to tracker |

| Imagehost.Chevereto | Description                                                                                                                         |
|---------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| host                | Hostname of the Chevereto image hoster                                                                                              |
| api_key             | API Key for the Chevereto image hoster. After registering and logging in to your account, you will find it in your profile settings |

Note: Chevereto is the image hosting software used by EMP. To use it, you need to create an account [here](https://hamster.is/) and generate an API key in your user profile.


| Torrent             | Description                                                                                                         |
|---------------------|---------------------------------------------------------------------------------------------------------------------|
| static_tags         | Tags to be added to every torrent                                                                                   |
| template            | Selects the BBCode template for the upload presentation. See the [templates](###Templates) section for more details |
| temporary_directory | Directory where the torrent is placed, ready to be uploaded to the tracker                                          |
| use_hardlinks       | If true, creates hard links instead of symlinks for the video file                                                  |


| Trackers     | Description                                      |
|--------------|--------------------------------------------------|
| name         | Tracker name, used for information only          |
| announce_url | Tracker announce url                             |
| source_tag   | Tracker specific source tag added to the torrent |
| category     | Tracker specific category, added as tag          |

## Usage/Examples
Example usage below (user wants to upload /tmp/my_video.mp4 and needs to provide only the path to local clip and the clipstore link):

```bash
clips2share

[Tracker(announce_url='http://tracker.empornium.sx:2710/yourpasskey/announce', category='Straight', source_tag='Emp')]

Video Path: /tmp/my_video.mp4
Clip Url: https://www.clips4sale.com/studio/12345/54321/my-video-1080p

C4SClip(title='My Video 1080p', studio='C4S Studio', price='$14.99 USD', date='3/1/25 1:23 AM', duration='15 min', size='1693 MB', format='mp4', resolution='1080p', description='The C4S Clip Description', category='POV', related_categories=['Glove', 'Leather Gloves', 'Play'], keywords=['Straight', 'POV'], url='https://www.clips4sale.com/studio/12345/54321/my-video-1080p', image_url='https://imagecdn.clips4sale.com/accounts123/54321/clip_images/previewlg_12345.jpg')
Processing /tmp/my_video.mp4...
Sampling... 16/16
Composing contact sheet...
Cleaning up temporary files...
creating torrent for Emp... Torrent(path=PosixPath('/tmp/upload/my_video'), name='My Video 1080p', trackers=[['http://tracker.empornium.sx:2710/yourpasskey/announce']], private=True, source='Emp', piece_size=2097152)
[/tmp/upload/my_video]   0 % done
[/tmp/upload/my_video] 100 % done
upload torrent to tracker Emp, than hit enter to autoload to qBittorrent...
```

### Templates

Default: `default_bbcode.jinja`

Available templates:
```
default_bbcode.jinja
fdc_iwc_white_by_ggg_bbcode.jinja
```
## Command-line Options

You can skip interactive prompts by using the following command-line arguments:

| Short | Long            | Type | Description                                                                   |
|-------|-----------------|------|-------------------------------------------------------------------------------|
| -V    | --video         | Path | Path to the local video file                                                  |
| -u    | --url           | URL  | Clip Store URL                                                                |
| -D    | --delay-seconds | Int  | Delay (in seconds) before autoloading the torrent when `delayed_seed` is true |

### Example:
```bash
clips2share -V "/tmp/my_video.mp4" -u "https://www.clips4sale.com/studio/12345/54321/my-video-1080p" -D 300
```

## Environment Variables

This optional environment variable allows to overwrite the path to the config (will be preferred instead of the user_config_dir)

`C2S_CONFIG_PATH`: `/path/to/config.toml`


## Contributing

Contributions are always welcome! Please make sure to:

- Create a pull request for each addition or fix - do NOT merge them into one PR 
- Write a description in your PR what it does, unless referred to another existing ticket 
- For larger PR we recommend you to either create an issue first or come by to our discord channel for discussion
- Update the README in your PR in case something changes here
- Check the CI Pipeline for success, after you opened your PR or fix by adding commits to your existing branch

## Contact

For feedback, feature requests or bug reports please create an issue or join our [discord developer channel](https://discord.gg/45beWDKq)


## License

[MIT](https://choosealicense.com/licenses/mit/)