Talon

https://talonvoice.com/docs
Admin
Talon is a powerful hands-free input replacement system that enables computer proficiency through...
Tokens:4,686
Snippets:41
Trust Score:8.7
Update:10 months ago
Show doc for...
Tokens:
Raw
### Advanced .talon File Configuration

Source: https://talonvoice.com/docs/index

This example demonstrates a more complex .talon file. It includes criteria for application-specific activation (Chrome), setting script settings (key_wait), activating tags, and defining multiple voice commands with varying actions like typing text and simulating key presses.

```talon
# activate this .talon file if the current app name is "Chrome"
# you can find app names by running ui.apps() in the REPL
app.name: Chrome
- 
# key_wait increases the delay when pressing keys (milliseconds)
# this is useful if an app seems to jumble or drop keys
settings():
    key_wait = 4.0

# activate the global tag "browser"
tag(): browser

# define some voice commands
hello chrome: "hello world"
switch tab: key(ctrl-tab)
go to google:
    # note: use key(cmd-t) on Mac
    key(ctrl-t)
    insert("google.com")
    key(enter)

```

--------------------------------

### Register for Talon App Events

Source: https://talonvoice.com/docs/index

Demonstrates how to register a callback function for application events using `app.register`. This allows scripts to react to events like Talon becoming ready, launching, or starting up with the system.

```python
from talon import app

def app_ready():
    print("Talon is ready")
app.register("ready", app_ready)

```

--------------------------------

### Manage Clipboard Text

Source: https://talonvoice.com/docs/index

Provides functions to check clipboard mode support, get, set, and clear text content. It supports various modes like 'main', 'select', and 'find'.

```python
from talon import clip

# Check if a clipboard mode is supported
print(clip.has_mode("main"))

# Get text from clipboard
text = clip.text()
print(text)

# Set text in clipboard
clip.set_text("Hello, Talon!")

# Clear clipboard
clip.clear()

# Revert clipboard changes within a context
with clip.revert():
    clip.set_text("Temporary text")

```

--------------------------------

### Set Talon Context Settings

Source: https://talonvoice.com/docs/index

Demonstrates setting context-specific configurations using the `ctx.settings` dictionary. This allows for fine-tuning Talon's behavior on a per-context basis, such as adjusting input wait times.

```python
from talon import Context
c_tx = Context()

c_tx.settings = {
    "input_wait": 1.0,
}

```

--------------------------------

### Configure Talon Context Apps

Source: https://talonvoice.com/docs/index

Demonstrates configuring application-specific rules for a Talon Context using the `ctx.apps` dictionary. This allows different matching rules to be applied for different applications within the same context.

```python
from talon import Context
c_tx = Context()

c_tx.apps["chrome"] = r"""
os: windows
app.name: Google Chrome
"""

```

--------------------------------

### Create Talon Context

Source: https://talonvoice.com/docs/index

Demonstrates how to create a new Talon Context object. Contexts are used to group related commands and configurations. No specific dependencies are required beyond the Talon library.

```python
from talon import Context
c_tx = Context()

```

--------------------------------

### Define a Simple Voice Command in Talon

Source: https://talonvoice.com/docs/index

This snippet shows how to create a basic voice command in a .talon file. When the user says 'hello talon', Talon will type 'hello world'. This is the fundamental way to add custom commands.

```talon
hello talon: "hello world"

```

--------------------------------

### Create Talon Module

Source: https://talonvoice.com/docs/index

Illustrates how to create a Talon Module object. Modules are used to organize code and can contain actions, settings, lists, and modes.

```python
from talon import Module
mod = Module()

```

--------------------------------

### Define Module Setting

Source: https://talonvoice.com/docs/index

Shows how to define a configurable setting for a module using `mod.setting`. Settings allow users to customize module behavior. Each setting requires a name, type, and optionally a default value and description.

```python
from talon import Module
mod = Module()

mod.setting("setting_name", int, default=0, desc="an example integer setting")
mod.setting("setting_name_2", str, default='', desc="an example string setting")

```

--------------------------------

### Set Talon Context Matches

Source: https://talonvoice.com/docs/index

Shows how to define activation criteria for a Talon Context using the `ctx.matches` property. This property takes a string containing a grammar definition that specifies when the context should be active, typically based on the operating system and application.

```python
from talon import Context
c_tx = Context()

c_tx.matches = r"""
os: windows
app.name: Slack
"""

```

--------------------------------

### Define Module List

Source: https://talonvoice.com/docs/index

Illustrates defining a named list for a module using `mod.list`. These lists can be populated by other parts of Talon or by users. A description can be provided for clarity.

```python
from talon import Module
mod = Module()

mod.list("list_name", desc="list description")

```

--------------------------------

### Define Talon Context Selections

Source: https://talonvoice.com/docs/index

Illustrates defining context-specific selections using the `ctx.selections` dictionary. Selections can be used to provide subsets of text or data that can be referenced within Talon commands.

```python
from talon import Context
c_tx = Context()

c_tx.selections["user.listname"] = """
some text to use for a subset selection
"""

```

--------------------------------

### Assign Talon Context Tags

Source: https://talonvoice.com/docs/index

Shows how to assign tags to a Talon Context using the `ctx.tags` property. Tags are used to categorize contexts and can be used to activate or deactivate sets of commands.

```python
from talon import Context
c_tx = Context()

c_tx.tags = ["user.terminal"]

```

--------------------------------

### Display Talon Desktop Notification

Source: https://talonvoice.com/docs/index

Illustrates how to display a desktop notification using `app.notify`. Notifications can include a title, subtitle, and body text. An option to play a sound is also available.

```python
from talon import app

app.notify(body="Hello world")
app.notify(title="Hello world",
           subtitle="Welcome to Talon",
           body="Enjoy your stay.",
           sound=True)

```

--------------------------------

### Assign Talon Context Lists

Source: https://talonvoice.com/docs/index

Shows how to assign lists to a Talon Context using the `ctx.lists` dictionary. These lists can contain words or phrases that Talon can recognize and use in commands. They can be defined as simple lists or as dictionaries for more complex mappings.

```python
from talon import Context
c_tx = Context()

c_tx.lists["user.listname"] = ["word", "word2"]
c_tx.lists["user.listname"] = {
    "pronunciation": "word",
}

```

--------------------------------

### Define Module Mode

Source: https://talonvoice.com/docs/index

Shows how to define a mode for a module using `mod.mode`. Modes allow for different sets of commands or behaviors to be active depending on the current mode.

```python
from talon import Module
mod = Module()

mod.mode("mode_name", desc="mode description")

```

--------------------------------

### Define Module Tag

Source: https://talonvoice.com/docs/index

Illustrates defining a tag for a module using `mod.tag`. Tags are used to categorize modules and can be used for activating or deactivating sets of commands or contexts.

```python
from talon import Module
mod = Module()

mod.tag("tag_name", desc="tag description")

```

--------------------------------

### Clipboard Operations

Source: https://talonvoice.com/docs/index

Provides functions to interact with the system clipboard, including checking supported modes, retrieving and setting text or image content, clearing the clipboard, and capturing changes.

```APIDOC
## talon.clip

### has_mode

Check if a clipboard mode is supported.

**Parameters**
- `_mode` (str) - The clipboard mode to check (e.g., "main", "select", "find").

**Returns**
- `bool` - True if the mode is supported, False otherwise.

### text

Get the text contents of the clipboard.

**Parameters**
- `_mode` (str, optional) - The clipboard mode to retrieve text from. Defaults to None.

**Returns**
- `str | None` - The text content of the clipboard, or None if unavailable.

### set_text

Set the text contents of the clipboard.

**Parameters**
- `_s` (str) - The text string to set as the clipboard content.
- `_mode` (str, optional) - The clipboard mode to set text in. Defaults to None.

### image

Get the image contents of the clipboard.

**Parameters**
- `_mode` (str, optional) - The clipboard mode to retrieve image from. Defaults to None.

**Returns**
- `Image | None` - The image content of the clipboard, or None if unavailable.

### set_image

Set the image contents of the clipboard.

**Parameters**
- `_image` (Image) - The image object to set as the clipboard content.
- `_mode` (str, optional) - The clipboard mode to set image in. Defaults to None.

### clear

Clear the clipboard.

**Parameters**
- `_mode` (str, optional) - The clipboard mode to clear. Defaults to None.

### revert

Restore the old contents of the clipboard after running a block.

**Parameters**
- `_old` (PyMimeData, optional) - The previous clipboard data to revert to. Defaults to None.
- `_mode` (str, optional) - The clipboard mode to revert. Defaults to None.

**Example**
```python
from talon import clip

with clip.revert():
    clip.set_text("this will only be set temporarily")
```

### capture

Capture a change in the clipboard, then restore the old text contents.

**Parameters**
- `_timeout` (float, optional) - The maximum time to wait for a change. Defaults to 0.5.
- `_inc` (int, optional) - Increment value. Defaults to 0.
- `_mode` (str, optional) - The clipboard mode to capture from. Defaults to None.
- `_formats` (list[str], optional) - A list of desired data formats. Defaults to None.

**Returns**
- `Generator[ChangePromise, None, None]` - A generator that yields clipboard change promises.

**Example**
```python
from talon import actions, clip

with clip.capture() as s:
    actions.edit.copy()
print(s.get())
```
```

--------------------------------

### Define Talon Action Function

Source: https://talonvoice.com/docs/index

Shows how to define an individual action using the `@ctx.action` decorator. This method is suitable for simpler actions or when not grouping actions within a class. The path specifies the action's name.

```python
from talon import Context
c_tx = Context()

@ctx.action('prefix.action_name')
def action_name():
    print("Running actions.prefix.action_name()")

```

--------------------------------

### Manage Clipboard Images

Source: https://talonvoice.com/docs/index

Functions to retrieve and set image data in the clipboard. Requires an Image object for setting and returns an Image object or None.

```python
from talon import clip

# Get image from clipboard
image = clip.image()

# Set image in clipboard (assuming 'my_image' is an Image object)
# clip.set_image(my_image)

```

--------------------------------

### Define Talon Dynamic List

Source: https://talonvoice.com/docs/index

Illustrates defining a dynamic list using `@ctx.dynamic_list`. Dynamic lists allow for lists of words or phrases that can change at runtime, often based on context or external data. The function should return a string, list, or dictionary.

```python
from talon import Context
c_tx = Context()

@ctx.dynamic_list('prefix.list_name')
def list_name(phrase: list[str]) -> Union[str, list[str], dict[str, str]]:
    return ['word one', 'word two']

```

--------------------------------

### File System Watcher

Source: https://talonvoice.com/docs/index

Enables monitoring of specified file system paths for changes, deletions, or renames, and allows registration and unregistration of callback functions.

```APIDOC
## talon.fs

### watch

Watch a path for changes and call a callback function when changes occur.

**Parameters**
- `_path` (PathLike) - The file system path to watch.
- `_cb` (Callable[[str, FsEventFlags], None]) - The callback function to execute upon change. It receives the path and event flags.

**Example**
```python
from talon import fs

def on_change(path, flags):
    if flags.renamed:
        print("renamed", path)
    if flags.exists:
        print("changed", path)
    else:
        print("deleted", path)

fs.watch('/path/to/stuff', on_change)
```

### unwatch

Remove a previously registered callback function from watching a specific path.

**Parameters**
- `_path` (PathLike) - The file system path being watched.
- `_cb` (Callable[[str, FsEventFlags], None]) - The callback function to unregister.
```

--------------------------------

### Define Module Action Class

Source: https://talonvoice.com/docs/index

Demonstrates defining actions within a module using the `@mod.action_class` decorator. This is the primary way to define actions that are part of a reusable module. Actions can have descriptions, arguments, and return types.

```python
from talon import Module
mod = Module()

@mod.action_class
class Actions:
    def action_name():
        "Description of the action"

    def second_action(arg1: int, arg2: str='') -> str:
        "Action with arguments, return type, and body"
        return 'test'

```

--------------------------------

### Define Module Action Function

Source: https://talonvoice.com/docs/index

Shows how to define an individual action within a module using the `@mod.action` decorator. This is suitable for simpler actions or when not using an action class. The action function should have a docstring describing its purpose.

```python
from talon import Module
mod = Module()

@mod.action
def action_name():
    "Description of the action"

```

--------------------------------

### Noise Event Handling

Source: https://talonvoice.com/docs/index

Allows for registration and unregistration of callback functions for specific noise events like 'pop' or 'hiss', or for all noise events.

```APIDOC
## talon.noise

### register

Register a callback function for a specific noise event.

**Parameters**
- `_topic` (Any) - The noise event topic to register for (e.g., "pop", "hiss", or an empty string for all events).
- `_cb` (Callable) - The callback function to execute when the event occurs.

**Example**
```python
from talon import noise

def on_pop(active):
    print("pop")
noise.register("pop", on_pop)

def on_hiss(active):
    print("hiss", active)
noise.register("hiss", on_hiss)
```

### unregister

Unregister a previously registered callback function for a noise event.

**Parameters**
- `_topic` (Any) - The noise event topic to unregister from.
- `_cb` (Callable) - The callback function to unregister.

**Example**
```python
noise.unregister("pop", on_pop)
```
```

--------------------------------

### Watch File System Changes

Source: https://talonvoice.com/docs/index

Monitors a specified file path for changes, including creation, modification, deletion, and renaming. A callback function is executed upon detecting any event.

```python
from talon import fs

def on_change(path, flags):
    if flags.renamed:
        print(f"Renamed: {path}")
    if flags.exists:
        print(f"Changed: {path}")
    else:
        print(f"Deleted: {path}")

fs.watch('/path/to/your/directory', on_change)
# To stop watching:
# fs.unwatch('/path/to/your/directory', on_change)

```

--------------------------------

### Define Talon Action Class

Source: https://talonvoice.com/docs/index

Illustrates defining actions within a class context using the `@ctx.action_class` decorator. This is useful for organizing related actions under a specific context. The action class requires a name matching the context's action path.

```python
from talon import Context
c_tx = Context()

@ctx.action_class('prefix')
class Actions:
    def action_name():
        print("Running actions.prefix.action_name()")

```

--------------------------------

### Capture Clipboard Changes

Source: https://talonvoice.com/docs/index

Captures changes to the clipboard and allows restoring previous content. Useful for operations that temporarily modify the clipboard, like copy actions.

```python
from talon import actions, clip

with clip.capture() as s:
    actions.edit.copy() # Perform an action that modifies the clipboard
print(s.get()) # Get the captured clipboard content

```

--------------------------------

### Define Talon Capture Rule

Source: https://talonvoice.com/docs/index

Demonstrates defining a capture rule using `@ctx.capture`. Captures are used to extract specific information from spoken phrases based on defined grammar rules. The `rule` parameter specifies the grammar.

```python
from talon import Context
c_tx = Context()

@ctx.capture('number', rule='(one | two)')
def number(m) -> int:
    return 1 if m[0] == 'one' else 2

```

--------------------------------

### Define Module Capture

Source: https://talonvoice.com/docs/index

Illustrates defining a capture within a module using the `@mod.capture` decorator. Captures defined in modules are reusable across different contexts. The function should have a docstring and optionally a return type annotation.

```python
from talon import Module
mod = Module()

@mod.capture
def capture_name() -> str:
    "Description of the capture"

```

--------------------------------

### Define Module Scope

Source: https://talonvoice.com/docs/index

Demonstrates defining a scope for a module using the `@mod.scope` decorator. Scopes are used to provide context-specific data, often used for defining lists or variables that can be accessed by commands.

```python
from talon import Module
mod = Module()

@mod.scope
def scope():
    return {
        "key": "value",
    }

# call scope.update() at any time to force a scope update

```

--------------------------------

### Unregister from Talon App Events

Source: https://talonvoice.com/docs/index

Shows how to unregister a previously registered callback function for application events using `app.unregister`. This is useful for cleaning up event listeners when they are no longer needed.

```python
from talon import app

# Assuming app_ready was previously registered
# app.unregister("ready", app_ready)

```

--------------------------------

### Register and Unregister Noise Events

Source: https://talonvoice.com/docs/index

Allows registering callback functions for specific noise events like 'pop' or 'hiss', or for all noises using an empty string. Callbacks receive an 'active' status. Callbacks can also be unregistered.

```python
from talon import noise

def on_pop(active):
    print("Pop detected")

def on_hiss(active):
    print(f"Hiss detected, active: {active}")

# Register callbacks
noise.register("pop", on_pop)
noise.register("hiss", on_hiss)
noise.register("", lambda active: print("Any noise detected"))

# To unregister a specific callback:
# noise.unregister("pop", on_pop)

```
Tokens:
Raw