parg edited this page Jan 15, 2019 · 29 revisions

Table of Contents


Tags are a more flexible replacement for categories (downloads can have at most one category assigned for example)

Tag Types

Download State

There are a number of automatically assigned tags that denote a download's state (e.g. queued for seeding), or something directly related (active, inactive, paused).

It is possible to assign a script to be run when a download is added to a download state tag. However, note that these are non-persistent states and as such downloads will be re-assigned to tags when BiglyBT is restarted. For example, a 'complete' download will be assigned to the 'Complete' tag (and associated script run) whenever BiglyBT is started.

Download Category

To offer some support for existing categories within the Tag framework there is an automatically populated tag type to denote categories.


Manual tags are managed directly by the user for managing downloads. They can be created/deleted at will and downloads can be assigned to them as required. One or more downloads can be dragged to the sidebar to assign them to a tag or, if they are already tagged as such, to remove them from the tag. There are also various right-click options to manage tag assignments.

  • File Locations
Manual tags allow the specification of an initial-save location, move-on-complete and copy-on-complete. Note that to assign a tag to a download when adding the download you need to ensure that the 'torrent options dialog' is shown (See Tools->Options->Files: when opening a torrent, show torrent options dialog)
  • Share Ratio
Minimum share ratio - a seeding torrent won't lose its 'first-priority' status until this ratio is met
Target share ratio - a torrent will stop seeding once this ratio is met
Aggregate share ratio - torrents will stop seeding when the overall ratio for all torrents assigned to the tag is met
Aggregate has priority - individual torrents will be allowed to exceed their specific ratio in order to achieve the aggregate one
  • Auto-transcoding for a particular device profile
  • Execute On Assign
Allows the tag to be set to either start or stop downloads when they are assigned to the tag. There are also options to set the 'force start' attribute. A 'script' can also be set to be run on assignment, for example javascript( "print(\"assigned!\")" ). See 'JavaScript Constraints' below for more information on evaluation context.
This also supports 'option templates These can be used to set download options (e.g. connection limits) when a download is assigned to the Tag.
There is also an option to post a download's magnet URI to a chat channel. This can be used to automate the publishing of downloads to other people, or other BiglyBT instances that, say, have setup an RSS feed from a chat channel and enabled auto-download to mirror downloads.
Since 1701_B37 there is the ability to assign other tags to a download. This originally came from a user request to support multiple tag assignments for downloads from a Subscription. Rather than modify the Subscription to directly support more than one tag it seemed more flexible to go this route - the Subscription assigns to tag 'A' and then tag 'A' can be configured to trigger assignment to 'B', 'C'... if needed.
  • Limits
Controls how many downloads can be assigned to a Tag - older ones are automatically removed. How removal occurs can be specified (e.g. archive the download, move it to another tag) along with the ordering used to identify old ones for removal. Also a special limit of 999999 (yes, 6 nines) can be used to denote an actual limit of 0 (0 is already defined to mean 'unlimited') - hacktastic but there you go.
  • Upload Priority
Gives assigned downloads upload bandwidth priority over other non-upload-priority upload
  • First Priority Seeding
Forces any assigned download to be considered as a 'first-priority-seed' for seeding rule purposes.
  • Notifications
These options allow a Notification to be generated when an item is added to/removed from a Tag

IP Sets

The Speed Limit Scheduler can be used to configure mappings from peer connections to IP Set tags, either via IP range or country code. These tags can then be configured with upload/download limits if required to apply limits to the peers.


Properties can be applied to manual tags to automatically constrain their contents.


The 'Trackers' property allows assignment to a tag to be based on what tracker urls appear in the download's torrent. The values entered must be the FULL DNS names of the trackers required, comma separated. For example,


This is a special case that denotes the tag as holding downloads that have no other tags assigned. It is possible although likely pointless to set this property on more than one tag. In the UI there are some places where you can enable the 'Untagged' tag - what this actually does is create a tag named 'Untagged' and sets this property on it.


Simple constraints allow the content of a tag to be automatically derived from assignment of other tags and download state.

Various functions can be combined with "not" (!), "and" (&&), "or" (||) and "xor" (^). Brackets can also be used to specify operator precedence.

For example, to create a tag that contains all downloads that are not tagged as "good" use

!hasTag( "good" )

For a tag that contains downloads tagged as "documentary" or "book":

hasTag( "documentary" ) || hasTag( "book" )

Defined functions:

hasTag( "<tag_name>") - does the download have tag <tag_name> assigned

hasTagGroup( "<group_name>") - does the download have tag with a group of <group_name> assigned   since 1701_B04

countTag( "<tag_name>") - returns the number of items assigned to the Tag

hasNet( "<net_name>" ) - does the download have the network <net_name> enabled

isPrivate() - is a private torrent

isComplete()/isChecking()/isStopped()/isPaused()/isError() - is the download complete/checking/stopped(EXCLUDES paused downloads), paused or in error state

isForceStart() - is the download force start

canArchive() - can the download be archived

isMagnet() - is the download a magnet download

isLowNoise() - is a low noise download

isGE,isGT,isLE,isLT,isEQ,isNEQ - numeric comparison functions taking 2 arguments
 e.g. isGE( shareratio, 0.5 )

Since 1701_B12:
The above can be more naturally denoted using
>=, >, <=, <, ==, !=
 e.g. shareratio >= 0.5

contains( s1, s2 [,flags] ) - does string s1 contain s2. Default is case-sensitive - supply a flag value of 1 for case-insensitive matching (since 1701)
 e.g. contains( name, "TED" ) 

matches( s, regexp[, flags] ) - does string s match regular expression. Default is case-insensitive - supply a flag value of 0 for case-sensitive matching (since 1701)
 e.g. matches( name, "^[a-f]" ) - download name starts with a, b, c, d, e or f
 See for more details

Since 1701_B12:
hoursToSeconds/htos/h2s( numeric) - convert hours to seconds
daysToSeconds/dtos/d2s( numeric) - convert hours to seconds
weeksToSeconds/wtos/w2s( numeric) - convert hours to seconds

getConfig( c ) can be used to access configuration variables. Currently the following are supported:
  queue.seeding.ignore.share.ratio - Queue->Seeding->Ignore Rules: Ignore torrents that have a share ratio of ...

hasTagAge( "<tag_name>" ) - seconds download has been assigned to tag for. IS reset on removal from tag (c.f. tag_age)

Since 1701_B39:
lowercase( string ) - convert a string to lower case

Defined variables:

share_ratio: float - download's share ratio (Integer.MAX_VALUE or ∞ if no download)
name: string - download's name
age: numeric - seconds since download was added
percent: float - percentage completed
true: boolean - only use for this is when used alone to create a tag with all downloads
seeding_for: numeric - seconds download has been seeding for
downloading_for: numeric - seconds download has been downloading for
last_active: numeric - seconds since the download was last added to the 'active' tag
swarm_merge_bytes: numeric - number of bytes swarm merged
resume_in: numeric - number of seconds until a pause-for... download is resumed
min_of_hour: numeric - minute of the hour: 0 -> 59
hour_of_day: numeric - hour of the day: 0 -> 23
day_of_week: numeric - day of the week: 1=Sunday, 2=Monday etc.
seed_count: numeric - number of seeds
peer_count: numeric - number of peers
seed_peer_ratio: float - ratio of seeds to peers (Integer.MAX_VALUE or ∞ if no peers)
tag_age: numeric - seconds since download was assigned to the tag (NOT reset on removal from the tag)
completed_age: numeric - seconds since download completed
peer_max_completion: float - maximum completion of connected peers
leech_max_completion : float - maximum completion of connected leechers (i.e. seeds are ignored)
peer_average_completion: float - average completion of connected peers and ourselves 
size, size_mb, size_gb: numeric - size of torrent file in bytes/MB/GB
file_count: numeric - number of files in the download
file_names: String[] - file names in torrent - for use with 'matches' and 'contains' functions
availability: float - availability of the download
up_idle: numeric - seconds since data last uploaded (Long.MAX_VALUE if never uploaded)
down_idle: numeric - seconds since data last downloaded (Long.MAX_VALUE if never downloaded)

Since 1701_B08:

downloaded: numeric - number of verified data bytes downloaded
uploaded: numeric - number of data bytes uploaded

Since 1701_B39:

save_path: String - download's save location
save_folder: String - parent folder of save_path

Of course this could be extended to be a general constraint language allowing reasoning about various properties, please make your case for extensions!

JavaScript Constraints

This requires Java the installation of the 'JavaScript Provider' plugin - see

To invoke JavaScript use the constraint function 'javascript' and supply the script to be executed as a string. For example:

javascript( "download.getTorrent().getSize() > 100*1024*1024" )

The script should return a boolean indicating whether or not the download should be assigned to the tag or not.

The script can call existing functions defined within the JavaScript Provider plugin 'general script' area or loaded from other .js files if required.

See JavaScript Tag Constraints for more information.

Constraint Scope

The scope of a constraint can be set. By default the constraint is applied to determine whether or not a download should be added to or removed from the tag. The new feature allows you to specify whether only half of this process should be applied - either only to determine if a download is to be added (with manual removal) or vice-versa (manual addition, automatic removal). Of course, if you manually remove a download from a tag while the constraint is still active then it will be re-added to it.

Consider a tag, say 'priority_downloads', that has no rate limits - you manually assign downloads as you see fit. Once the download is complete though it would be nice if they automatically removed themselves from it. This can be achieved by setting the tag with a constraint of "!isComplete()" and a scope of 'removal only'

Tracker Templates

A manual tag can have one or more tracker templates (see Tracker Templates and Lists ) and operations applied to it so that when a download is assigned to the tag trackers are set/merged/removed


  • Add Trackers
You can automatically add a set of trackers to downloads that are assigned to a Tag as follows.
  1. Create the Tag to perform this function (call it 'AddedTrackers' say)
  2. Right-click on the AddedTrackers Tag and select 'Tracker Templates->New...' to create a new tracker template. Enter a name (say 'Added'), hit the 'edit as text' button and paste in your new tracker announce URLs, one per line with a blank line between each entry). Save the template
  3. Now assign that template with a 'merge' action by right-clicking on AddedTrackers Tag again, selecting 'Tracker Templates->Added->Merge'
If you wanted to automatically do this for all torrents then set the constraint for the 'AddedTrackers' Tag to 'true' to ensure that all torrents are assigned to it
  • Remove Dead Trackers
You can automatically remove a set of dead trackers from torrents that are assigned to a Tag as follows.
  1. Create the Tag to perform this function (call it 'DeadTrackers' say)
  2. Right-click on the DeadTrackers Tag and select 'Tracker Templates->New...' to create a new tracker template. Enter a name (say 'Dead'), hit the 'edit as text' button and paste in your dead tracker announce URLs, one per line with a blank line between each entry). Save the template
  3. Now assign that template with a 'remove' action by right-clicking on DeadTrackers Tag again, selecting 'Tracker Templates->Dead->Remove'
If you wanted to automatically do this for all torrents then set the constraint for the 'DeadTrackers' Tag to 'true' to ensure that all torrents are assigned to it

RSS Feeds

You can have an RSS feed automatically generated from a tag's contents by doing the following:

  • Enable local RSS feeds via Tools->Options->Local RSS etc. Review the various parameters there to control access to these local feeds. You can click on the link at the top of the options panel to view a (very simple) webpage that links to the various RSS feeds you have enabled
  • Right-click on a tag and select 'Create Local RSS Feed' to generate a feed for that tag
Once configured you can go to the local webpage, click on the 'tags' link and find the URL for the RSS feed generated for a particular tag.

Tag-based RSS feeds are useful if you want to share a set of downloads with others. If you make the feeds public, for example, others can add the feed to their client to access the downloads. Alternatively you can use the RSS To Chat plugin to automatically post details of downloads assigned to a tag to a chat channel of your choice (optionally anonymous) for other users to see.

User Interface

Tags can be displayed in the sidebar in the same way that categories can. Right-click on the 'My Torrents' sidebar entry to show a menu that has options controlling visibility.

In a similar vein, tag buttons can be enabled in Library views to filter on tag - right-click on the Library view header area for a menu.

To see all the details of all your Tag use the 'Tags Overview' view - look at the main 'View' menu in the client to show this.

By default the order of the tags in the sidebar, and tag button order in Library views, is alphanumeric. This can be further refined by using 'groups' to group sets of tags into similar sets. Groups are sorted first and then the tags within them. The use of a numeric prefix can be used with groups if desired to force a particular order.

There are also some UI options under Tools->Options->Interface->Tables

Tag Discoveries

The Tag Discoveries view allows you to see tags that other people have publicly assigned to the torrents you have. Use View->Tag Discoveries to show the view, and click the Scan button to start the tag lookup.


Stop Seeding After Time Limit

Create a Tag and set its 'execute on assign' to 'Stop'

Set the Tag's constraint to auto-assign downloads after they have been seeding for a time with

isGE( seedingfor, <time_in_seconds>)

Play A Sound When Share Ratio Met

Set up a Tag with a constraint that causes downloads to be assigned to it when they meet the required share ratio (e.g. 1.0)

isGE( shareratio, 1.0 )

Go to the Tag settings and enable the 'Post message to notifications: on addition' option.

Configure notifications to play an alert via Tools->Options->Interface->Alerts: Play a sound when notification added

Inactive Downloads

The following constraint selects downloads that haven't been active in the last 30 days. Note that it also excludes downloads that have never been active by checking against a large upper bound (around 100 years in this case) as such downloads have a 'last_active' of Long.MAX_VALUE.

isGT( last_active, 2592000 ) && isLT( last_active, 3153600000 )

Re-archive files after a time period

When an archived file is restored it is automatically assigned to the 'Restored' tag. In order to automatically re-archive files after a number T of seconds you can achieve this by doing the following:

1) create a tag, 'Restored_Recently' (say) and set its constraint to be

hasTag( "Restored" ) && isLT( tag_age, T )

2) create a tag, 'Restored_Temp' (say) and set its constraint to be

hasTag( "Restored_Recently" )

This intermediate tag is required to ensure that a restored download has been added to 'Restored_Recently' before it is considered for re-archive.

3) create another tag, 'Restored_Old' (say) and set its constraint to be

hasTag( "Restored_Temp") && !hasTag( "Restored_Recently" )

Also set its 'execute on assign' action to 'Stop' and configure its 'limits' to have a count of 999999 (see above, hack to denote 0) and removal policy of 'Archive'

Assign download connection limits based on Tracker

Use 'Tracker Properties' to automatically assign the desired downloads to a Tag. Then also set that Tag's 'Execute On Assign' value via right-clicking on it - select the 'Apply Options Template' item and then configure the settings as desired.

Tell other users when a download is assigned to a Tag

Decentralized chat channels can be used to communicate with other users and are used in this example. Say you want to automatically post a magnet link for a download to chat channel 'CoolStuff' when a download is assigned to Tag 'Cool':

  • Create the Tag 'Cool' and enable the 'save messages across restart' option
  • Enable 'Local RSS etc.' in Tools->Options->Local RSS etc. and configure as required
  • Right-click on the 'Cool' Tag in the sidebar and enable 'Create local RSS feed'
  • Go back to Tools->Options->Local RSS etc. and click the 'Click to view the local home page' link at the top
  • When the browser opens navigate to the 'Cool' Tag RSS link (something like - this will show an RSS feed generated from the Tag's contents
  • Add the RSS URL as a new Subscription in BiglyBT via the sidebar Subscriptions entry
  • Install the 'RSSToChat' plugin and configure it to post messages from the Subscription to the 'CoolStuff' chat
  • Job done!
Since 1601 an 'execute on assign' option has been introduced to give an alternative and simpler way of achieving this.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.