Tags

Tags

Tags were introduced in Vuze 5.0.0.0 as 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).

Since 5701 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 Vuze is restarted. For example, a 'complete' download will be assigned to the 'Complete' tag (and associated script run) whenever Vuze 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

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

• Action 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. Since 5701 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.

• 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, since 5751_B3 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.

• 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

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

Trackers

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

tracker.publicbt.com, tracker.openbittorrent.com

Untagged

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.

Constraints

Simple constraints were added in 5301_B10 to 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

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

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

contains( s1, s2 ) - does string s1 contain s2
 e.g. contains( name, "TED" ) 

matches( s, regexp ) - does string s match regular expression 
 e.g. matches( name, "^[a-f]" ) - download name starts with a, b, c, d, e or f

Defined variables:

share_ratio: numeric - download's share ratio
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: numeric - ratio of seeds to peers
tag_age: numeric - seconds since download was assigned to the tag (5751_B3+)

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

Since 5701 support for constraints written in JavaScript has been introduced. It requires Java 1.8 or higher and the installation of the 'JavaScript Provider' plugin - see http://plugins.vuze.com/details/azjscripter.

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

Since 5730 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 and operations applied to it so that when a download is assigned to the tag trackers are set/merged/removed

Examples

• 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.

Examples

Stop Seeding After Time Limit

Create a Tag and set its 'action 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, with 5751_B3+ 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'