subconverter

Utility to convert between various proxy subscription formats.

Docker README

中文文档

• subconverter
  • Supported Types
  • Quick Usage
    • Access Interface
    • Description
    • Quick Conversion
  • Advanced Usage
    • Read Before Continue
    • Advanced Details
    • Profiles
    • Configuration File
    • External Configuration File
  • Auto Upload

Supported Types

Type	As Source	As Target	Target Name
Clash	✓	✓	clash
ClashR	✓	✓	clashr
Quantumult	✓	✓	quan
Quantumult X	✓	✓	quanx
Loon	✓	✓	loon
SS (SIP002)	✓	✓	ss
SS Android	✓	✓	sssub
SSD	✓	✓	ssd
SSR	✓	✓	ssr
Surfboard	✓	✓	surfboard
Surge 2	✓	✓	surge&ver=2
Surge 3	✓	✓	surge&ver=3
Surge 4	✓	✓	surge&ver=4
V2Ray	✓	✓	v2ray
Telegram-liked HTTP/Socks 5 links	✓	×	Only as source

Notice:

1. Shadowrocket users should use ss, ssr or v2ray as target.

2. You can add &remark= to Telegram-liked HTTP/Socks 5 links to set a remark for this node. For example:

   • tg://http?server=1.2.3.4&port=233&user=user&pass=pass&remark=Example

   • https://t.me/http?server=1.2.3.4&port=233&user=user&pass=pass&remark=Example

---

Quick Usage

Using default groups and rulesets configuration directly, without changing any settings

Access Interface

http://127.0.0.1:25500/sub?target=%TARGET%&url=%URL%&config=%CONFIG%

Description

Argument	Needed	Example	Explanation
target	Yes	clash	Target subscription type. Acquire from Target Name in Supported Types.
url	Yes	https%3A%2F%2Fwww.xxx.com	Subscription to convert. Supports URLs and file paths. Process with URLEncode first.
config	No	https%3A%2F%2Fwww.xxx.com	External configuration file path. Supports URLs and file paths. Process with URLEncode first. More examples can be found in this repository. Default is to load configurations from pref.ini.

If you need to merge two or more subscription, you should connect them with '|' before the URLEncode process.

Example:

You have 2 subscriptions and you want to merge them and generate a Clash subscription:
1. https://dler.cloud/subscribe/ABCDE?clash=vmess
2. https://rich.cloud/subscribe/ABCDE?clash=vmess

First use '|' to separate 2 subscriptions:
https://dler.cloud/subscribe/ABCDE?clash=vmess|https://rich.cloud/subscribe/ABCDE?clash=vmess

Then process it with URLEncode to get %URL%:
https%3A%2F%2Fdler.cloud%2Fsubscribe%2FABCDE%3Fclash%3Dvmess%7Chttps%3A%2F%2Frich.cloud%2Fsubscribe%2FABCDE%3Fclash%3Dvmess

Then fill %TARGET% and %URL% in Access Interface with actual values:
http://127.0.0.1:25500/sub?target=clash&url=https%3A%2F%2Fdler.cloud%2Fsubscribe%2FABCDE%3Fclash%3Dvmess%7Chttps%3A%2F%2Frich.cloud%2Fsubscribe%2FABCDE%3Fclash%3Dvmess

Finally subscribe this link in Clash and you are done!

Quick Conversion

When the Surge configuration file has already meet your requirements, but you also need a same Clash configuration with the same groups and rules, you can use the following method:

http://127.0.0.1:25500/surge2clash?link=url_to_Surge_subscription

Here url_to_Surge_subscription does not need to be URLEncoded and no other configuration is needed.

---

Advanced Usage

If you are not satisfied with the default groups and rulesets, you can try out advanced usage. Customize more settings in Access Interface and pref.ini to satisfy various needs.

Read Before Continue

It is strongly recommended to read the following articles before continuing:

1. Related to pref.ini: INI file
2. Related to Clash configurations: YAML Syntax
3. Often needed: Learn Regular Expression
4. When you want to write an ISSUE: How To Ask Questions The Smart Way

Subconverter only guaranteed to work with default configurations.

Advanced Details

Access Interface

http://127.0.0.1:25500/sub?target=%TARGET%&url=%URL%&emoji=%EMOJI%····

Description

Argument	Needed	Example	Explanation
target	Yes	quan	Target subscription type. Acquire from Target Name in Supported Types.
url	No	https%3A%2F%2Fwww.xxx.com	Subscription to convert. Supports URLs, data URIs, and file paths. Process with URLEncode first. **Not needed ONLY WHEN YOU HAVE SET default_urls IN pref.ini.
config	No	https%3A%2F%2Fwww.xxx.com	External configuration file path. Supports URLs and file paths. Process with URLEncode first. More examples can be found in this repository. Default is to load configurations from pref.ini.
upload	No	true / false	Upload generated configuration to Gist repository. gistconf.ini must be filled before uploading. Default is false.
upload_path	No	MySS.yaml	File name when uploaded to Gist. Process with URLEncode first.
emoji	No	true / false	Adding Emoji to node remarks. Default is true.
group	No	MySS	Set a custom group for generated configuration. Often needed in SSD/SSR subscription.
tfo	No	true / false	Enable TCP Fast Open for all nodes. Default is false.
udp	No	true / false	Enable UDP for all nodes. Default is false.
scv	No	true / false	Enable Skip Cert Verify for all nodes. Default is false.
list	No	true / false	Generate Surge Node List or Clash Proxy Provider. Default is false.
sort	No	true / false	Sort nodes in alphabetical order. Default is false.
include	No	See include_remarks	Exclude nodes which remarks match the following patterns. Supports regular expression. Process with URLEncode first. WILL OVERRIDE THE SAME SETTING IN pref.ini
exclude	No	See exclude_remarks	Only include nodes which remarks match the following patterns. Supports regular expression. Process with URLEncode first. WILL OVERRIDE THE SAME SETTING IN pref.ini
filename	No	MySS	Set the file name while downloading. Can be used as a profile name in Clash for Windows.

Example:

You have the following subscription: `https://dler.cloud/subscribe/ABCDE?clash=vmess`, and you want to convert it to Surge 4 subscription, set UDP and TFO to enabled,
add Emoji to node remarks and filter out unused nodes named "剩余流量：1024G" and "官网地址：dler.cloud".

First find all needed arguments: 
target=surge, ver=4,  tfo=true, udp=true, emoji=true, exclude=(流量|官网)
url=https://dler.cloud/subscribe/ABCDE?clash=vmess

Then process any argument that requires URLEncode: 
exclude=%28%E6%B5%81%E9%87%8F%7C%E5%AE%98%E7%BD%91%29
url=https%3A%2F%2Fdler.cloud%2Fsubscribe%2FABCDE%3Fclash%3Dvmess

Then merge everything into a single URL: 
http://127.0.0.1:25500/sub?surge&ver=4&tfo=true&udp=true&emoji=true&exclude=%28%E6%B5%81%E9%87%8F%7C%E5%AE%98%E7%BD%91%29&url=https%3A%2F%2Fdler.cloud%2Fsubscribe%2FABCDE%3Fclash%3Dvmess

Finally subscribe this link in Surge and you are done!

Profiles

After preparing all the arguments for the subscription link, it may be too long and hard to remember. Now you can consider setting up a profile.

For now only local profiles are allowed.

Interface for Profiles

http://127.0.0.1:25500/getprofile?name=%NAME%&token=%TOKEN%

Description

Argument	Needed	Example	Explanation
name	Yes	profiles/formyairport.ini	The path to the profile. (relative to the pref configuration)
token	Yes	passwd	The access token for authorization. (Please check api_access_token in the [common] section in pref configuration.

Notice that arguments in the profile does not require URLEncode.

Create a new text file only in the same directory or a sub-directory of the pref configuration (a sub-directory named profiles is recommended) and name it, for example formyairport.ini, then fill the arguments to the file according to the example profile, then you are good to go.

Example:

Using the same example in Advanced Usage, the content of formyairport.ini should be:

[Profile]
url=https://dler.cloud/subscribe/ABCDE?clash=vmess
target=surge
surge_ver=4
tfo=true
udp=true
emoji=true
exclude=(流量|官网)

After saving it to the profile directory, you can access http://127.0.0.1:25500/getprofile?name=profiles/formyairport.ini&token=passwd to read this profile.

Configuration File

Check comments inside pref.example.ini for more information.

External Configuration File

Most settings works the same as the ones with the same name inside pref.ini, you can check the example configuration file and comments inside pref.example.ini for more information.

Any setting defined in the external configuration file will override the ones from pref.ini.

For example, if you have the following lines inside the external configuration file:

emoji=(流量|时间|应急),🏳️‍🌈
emoji=阿根廷,🇦🇷

Then instead of the Emojis defined in pref.ini, the program will only use the newly defined ones.

Auto Upload

Upload Gist automatically

Add a Personal Access Token into gistconf.ini in the root directory, then add &upload=true to the local subscription link, then when you access this link, the program will automatically update the content to Gist repository.

Example:

[common]
;uncomment the following line and enter your token to enable upload function
token = xxxxxxxxxxxxxxxxxxxxxxxx(Your Personal Access Token)