JiWER

https://jitsi.github.io/jiwer
Admin
JiWER is a simple and fast Python package to evaluate automatic speech recognition systems using...
Tokens:18,551
Snippets:146
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install JiWER via uv

Source: https://jitsi.github.io/jiwer

Use uv to add the jiwer package to your project.

```bash
$ uv add jiwer
```

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

### Install JiWER via pip

Source: https://jitsi.github.io/jiwer

Use pip to install the package for Python 3.8 or higher.

```bash
$ pip install jiwer
```

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

### Visualize Alignment with Jiwer

Source: https://jitsi.github.io/jiwer/reference/alignment

This example demonstrates how to process word sequences and generate a visual alignment report.

```python
import jiwer

out = jiwer.process_words(
    ["short one here", "quite a bit of longer sentence"],
    ["shoe order one", "quite bit of an even longest sentence here"],
)

print(jiwer.visualize_alignment(out))
```

```txt
=== SENTENCE 1 ===

REF:    # short one here
HYP: shoe order one    *
        I     S        D

=== SENTENCE 2 ===

REF: quite a bit of  #    #  longer sentence    #
HYP: quite * bit of an even longest sentence here
           D         I    I       S             I

=== SUMMARY ===
number of sentences: 2
substitutions=2 deletions=2 insertions=4 hits=5

mer=61.54%
wil=74.75%
wip=25.25%
wer=88.89%
```

```txt
=== SENTENCE 1 ===

REF:    # short one here
HYP: shoe order one    *
        I     S        D

=== SENTENCE 2 ===

REF: quite a bit of  #    #  longer sentence    #
HYP: quite * bit of an even longest sentence here
           D         I    I       S             I
```

```txt
=== SENTENCE 1 ===

REF: This is a very  long sentence that is *** much longer than the previous one
HYP: This is a very loong sentence that is not much longer than the previous one
                       S                    I
REF: or the one before that
HYP: or *** one before that
          D
```

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

### Substitute substrings with SubstituteRegexes

Source: https://jitsi.github.io/jiwer/reference/transforms

Initial setup for using regex-based substitution on a list of strings.

```python
import jiwer

sentences = ["is the world doomed or loved?", "edibles are allegedly cultivated"]
```

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

### Visualize Error Counts Example

Source: https://jitsi.github.io/jiwer/reference/alignment

Example usage of visualize_error_counts to display alignment errors.

```python
import jiwer

out = jiwer.process_words(
    ["short one here", "quite a bit of longer sentence"],
    ["shoe order one", "quite bit of an even longest sentence here"],
)
print(jiwer.visualize_error_counts(out))
```

```txt
=== SUBSTITUTIONS ===
short   --> order   = 1x
longer  --> longest = 1x

=== INSERTIONS ===
shoe    = 1x
an even = 1x
here    = 1x

=== DELETIONS ===
here = 1x
a    = 1x
```

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

### Display JiWER CLI help information

Source: https://jitsi.github.io/jiwer/cli

Use this command to view available options and usage instructions for the JiWER CLI.

```bash
$ jiwer --help
Usage: jiwer [OPTIONS]

  JiWER is a python tool for computing the word-error-rate of ASR systems. To
  use this CLI, store the reference and hypothesis sentences in a text file,
  where each sentence is delimited by a new-line character. The text files are
  expected to have an equal number of lines, unless the `-g` flag is used. The
  `-g` flag joins computation of the WER by doing a global minimal alignment.

Options:
  -r, --reference PATH   Path to new-line delimited text file of reference
                         sentences.  [required]
  -h, --hypothesis PATH  Path to new-line delimited text file of hypothesis
                         sentences.  [required]
  -c, --cer              Compute CER instead of WER.
  -a, --align            Print alignment of each sentence.
  -g, --global           Apply a global minimal alignment between reference
                         and hypothesis sentences before computing the WER.
  --help                 Show this message and exit.
```

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

### Compose Initialization

Source: https://jitsi.github.io/jiwer/reference/transforms

Constructor signature and implementation for the Compose class.

```python
__init__(transforms)
```

```python
def __init__(self, transforms: List[AbstractTransform]):
    """

    Args:
        transforms: The list of transformations to chain.
    """
    self.transforms = transforms
```

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

### RemovePunctuation

Source: https://jitsi.github.io/jiwer/reference/transforms

Filters out punctuation characters from a list of strings. Punctuation is defined as all unicode characters with a category starting with 'P'.

```APIDOC
## RemovePunctuation

### Description
Filters out punctuation characters from input strings. Punctuation is defined as all unicode characters whose category name starts with 'P'.

### Usage
```python
import jiwer
sentences = ["this is an example!", "hello. goodbye"]
print(jiwer.RemovePunctuation()(sentences))
# prints: ['this is an example', "hello goodbye"]
```
```

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

### Define AlignmentChunk Dataclass

Source: https://jitsi.github.io/jiwer/reference/process

Represents an alignment between subsequences of reference and hypothesis strings. It includes validation logic to ensure start indices do not exceed end indices and normalizes 'replace' types to 'substitute'.

```python
@dataclass
class AlignmentChunk:
    """
    Define an alignment between two subsequence of the reference and hypothesis.

    Attributes:
        type: one of `equal`, `substitute`, `insert`, or `delete`
        ref_start_idx: the start index of the reference subsequence
        ref_end_idx: the end index of the reference subsequence
        hyp_start_idx: the start index of the hypothesis subsequence
        hyp_end_idx: the end index of the hypothesis subsequence
    """

    type: str

    ref_start_idx: int
    ref_end_idx: int

    hyp_start_idx: int
    hyp_end_idx: int

    def __post_init__(self):
        if self.type not in ["replace", "insert", "delete", "equal", "substitute"]:
            raise ValueError("")

        # rapidfuzz uses replace instead of substitute... For consistency, we change it
        if self.type == "replace":
            self.type = "substitute"

        if self.ref_start_idx > self.ref_end_idx:
            raise ValueError(
                f"ref_start_idx={self.ref_start_idx} "
                f"is larger "
                f"than ref_end_idx={self.ref_end_idx}"
            )
        if self.hyp_start_idx > self.hyp_end_idx:
            raise ValueError(
                f"hyp_start_idx={self.hyp_start_idx} "
                f"is larger "
                f"than hyp_end_idx={self.hyp_end_idx}"
            )
```

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

### Initialize SubstituteRegexes

Source: https://jitsi.github.io/jiwer/reference/transforms

Constructor for the SubstituteRegexes class.

```python
__init__(substitutions)
```

```python
def __init__(self, substitutions: Mapping[str, str]):
    """

    Args:
        substitutions: a mapping of regex expressions to replacement strings.
    """
    self.substitutions = substitutions
```

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

### Evaluate metrics with empty references

Source: https://jitsi.github.io/jiwer

Demonstrates how JiWER handles empty reference and hypothesis pairs to avoid division by zero errors.

```python
import jiwer

# when ref and hyp are both empty, there is no error as
# an ASR system correctly predicted silence/non-speech.
assert jiwer.wer('', '') == 0 
assert jiwer.mer('', '') == 0
assert jiwer.wip('', '') == 1
assert jiwer.wil('', '') == 0

assert jiwer.cer('', '') == 0
```

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

### WIP Implementation

Source: https://jitsi.github.io/jiwer/reference/measures

The source implementation of the wip function, which processes input strings and returns the calculated WIP value.

```python
def wip(
    reference: Union[str, List[str]] = None,
    hypothesis: Union[str, List[str]] = None,
    reference_transform: Union[tr.Compose, tr.AbstractTransform] = wer_default,
    hypothesis_transform: Union[tr.Compose, tr.AbstractTransform] = wer_default,
) -> float:
    """
    Calculate the word information preserved (WIP) between one or more reference and
    hypothesis sentences.

    Args:
        reference: The reference sentence(s)
        hypothesis: The hypothesis sentence(s)
        reference_transform: The transformation(s) to apply to the reference string(s)
        hypothesis_transform: The transformation(s) to apply to the hypothesis string(s)

    Returns:
        (float): The word information preserved of the given reference and
                 hypothesis sentence(s).
    """
    output = process_words(
        reference, hypothesis, reference_transform, hypothesis_transform
    )

    return output.wip
```

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

### jiwer.Compose

Source: https://jitsi.github.io/jiwer/reference/transforms

Initializes a pipeline of transformations to be applied sequentially to text data.

```APIDOC
## jiwer.Compose(transforms)

### Description
Chain multiple transformations back-to-back to create a pipeline combining multiple transformations. Note that each transformation needs to end with either `ReduceToListOfListOfWords` or `ReduceToListOfListOfChars`.

### Parameters
- **transforms** (List[AbstractTransform]) - Required - The list of transformations to chain.

### Example
```python
import jiwer

jiwer.Compose([
    jiwer.RemoveMultipleSpaces(),
    jiwer.ReduceToListOfListOfWords()
])
```
```

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

### ReduceToSingleSentence Constructor

Source: https://jitsi.github.io/jiwer/reference/transforms

Initializes the transform with a custom word delimiter.

```python
__init__(word_delimiter=' ')
```

```python
def __init__(self, word_delimiter: str = " "):
    """
    :param word_delimiter: the character which delimits words. Default is ` ` (space).
    """
    self.word_delimiter = word_delimiter
```

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

### ReduceToListOfListOfWords Initialization

Source: https://jitsi.github.io/jiwer/reference/transforms

Configures the word delimiter used to split sentences into words.

```python
def __init__(self, word_delimiter: str = " "):
    """
    Args:
        word_delimiter: the character which delimits words. Default is ` ` (space).
    """
    self.word_delimiter = word_delimiter
```

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

### SubstituteWords Initialization

Source: https://jitsi.github.io/jiwer/reference/transforms

Initializes the SubstituteWords transform with a mapping of words to their replacements.

```python
def __init__(self, substitutions: Mapping[str, str]):
    """
    Args:
        substitutions: A mapping of words to replacement words.
    """
    self.substitutions = substitutions
```

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

### visualize_alignment(output, show_measures=True, skip_correct=True, line_width=None)

Source: https://jitsi.github.io/jiwer/reference/alignment

Generates a string visualization of the alignment between processed reference and hypothesis pairs.

```APIDOC
## visualize_alignment(output, show_measures=True, skip_correct=True, line_width=None)

### Description
Visualize the output of jiwer.process_words and jiwer.process_characters. The visualization shows the alignment between each processed reference and hypothesis pair.

### Parameters
- **output** (Union[WordOutput, CharacterOutput]) - Required - The processed output of reference and hypothesis pair(s).
- **show_measures** (bool) - Optional - If enabled, the visualization will include measures like the WER or CER. Default: True.
- **skip_correct** (bool) - Optional - If enabled, the visualization will exclude correct reference and hypothesis pairs. Default: True.
- **line_width** (Optional[int]) - Optional - If set, try, at best effort, to split sentences into multiple lines if they exceed the width. Default: None.

### Returns
- **str** - The visualization as a string.
```

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

### Evaluate metrics with empty reference and non-empty hypothesis

Source: https://jitsi.github.io/jiwer

Shows how non-empty hypotheses are treated as insertions when the reference is empty.

```python
import jiwer

assert jiwer.wer('', 'silence') == 1
assert jiwer.wer('', 'peaceful silence') == 2
assert jiwer.process_words('', 'now defined behaviour').insertions == 3

assert jiwer.cer('', 'a') == 1
assert jiwer.cer('', 'abcde') == 5
```

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

### Apply Text Transformations

Source: https://jitsi.github.io/jiwer/usage

Use the Compose API to apply a sequence of transformations to inputs before metric calculation.

```python
import jiwer

tr = jiwer.Compose([
    jiwer.RemoveMultipleSpaces(),
    jiwer.Strip(),
    jiwer.SubstituteWords({"I'm": 'i am'}),
    jiwer.ReduceToListOfListOfWords()
])

out = jiwer.process_words(
    "I'm good", 
    "i am bad", 
    reference_transform=tr, 
    hypothesis_transform=tr
)
```

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

### wip(reference, hypothesis, reference_transform, hypothesis_transform)

Source: https://jitsi.github.io/jiwer/reference/measures

Calculates the word information preserved (WIP) between one or more reference and hypothesis sentences.

```APIDOC
## wip(reference, hypothesis, reference_transform, hypothesis_transform)

### Description
Calculates the word information preserved (WIP) between one or more reference and hypothesis sentences.

### Parameters
- **reference** (Union[str, List[str]]) - Optional - The reference sentence(s).
- **hypothesis** (Union[str, List[str]]) - Optional - The hypothesis sentence(s).
- **reference_transform** (Union[Compose, AbstractTransform]) - Optional - The transformation(s) to apply to the reference string(s). Defaults to wer_default.
- **hypothesis_transform** (Union[Compose, AbstractTransform]) - Optional - The transformation(s) to apply to the hypothesis string(s). Defaults to wer_default.

### Returns
- **float** - The word information preserved of the given reference and hypothesis sentence(s).
```

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

### Visualize Alignments

Source: https://jitsi.github.io/jiwer/usage

Generate a visual representation of the alignment between reference and hypothesis.

```python
import jiwer

out = jiwer.process_words(
    ["short one here", "quite a bit of longer sentence"],
    ["shoe order one", "quite bit of an even longest sentence here"],
)

print(jiwer.visualize_alignment(out))
```

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

### Substitute substrings using regex with SubstituteRegexes

Source: https://jitsi.github.io/jiwer/reference/transforms

Uses a mapping of regex patterns to replacement strings to transform input sentences.

```python
import jiwer

sentences = ["is the world doomed or loved?", "edibles are allegedly cultivated"]

# note: the regex string "\b(\w+)ed\b", matches every word ending in 'ed',
# and "\1" stands for the first group ('\w+). It therefore removes 'ed' in every match.
print(jiwer.SubstituteRegexes({r"doom": r"sacr", r"\b(\w+)ed\b": r"\1"})(sentences))

# prints: ["is the world sacr or lov?", "edibles are allegedly cultivat"]
```

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

### WIP Function Signature

Source: https://jitsi.github.io/jiwer/reference/measures

The function signature for calculating WIP, including default transformation parameters.

```python
wip(
    reference=None,
    hypothesis=None,
    reference_transform=wer_default,
    hypothesis_transform=wer_default,
)
```

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

### jiwer.visualize_alignment(output, show_measures=True, skip_correct=True, line_width=None)

Source: https://jitsi.github.io/jiwer/reference/alignment

Visualizes the alignment between processed reference and hypothesis pairs. It can optionally include calculated metrics like WER or CER and supports line wrapping.

```APIDOC
## visualize_alignment

### Description
Visualizes the alignment between each processed reference and hypothesis pair. If `show_measures` is enabled, the output string will also contain all calculated measures.

### Parameters
- **output** (Union[WordOutput, CharacterOutput]) - Required - The processed output of reference and hypothesis pair(s).
- **show_measures** (bool) - Optional - If enabled, the visualization will include measures like WER or CER. Defaults to True.
- **skip_correct** (bool) - Optional - If enabled, the visualization will exclude correct reference and hypothesis pairs. Defaults to True.
- **line_width** (Optional[int]) - Optional - If set, attempts to split sentences into multiple lines if they exceed the specified width.

### Returns
- **(str)** - The visualization as a formatted string.
```

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

### jiwer.SubstituteRegexes

Source: https://jitsi.github.io/jiwer/reference/transforms

Initializes a transformation that replaces substrings matching regex patterns with specified replacement strings.

```APIDOC
## class SubstituteRegexes(substitutions)

### Description
Transform strings by substituting substrings matching regex expressions into another substring.

### Parameters
- **substitutions** (Mapping[str, str]) - Required - A mapping of regex expressions to replacement strings.

### Usage Example
```python
import jiwer

sentences = ["is the world doomed or loved?", "edibles are allegedly cultivated"]

# The regex string "\b(\w+)ed\b" matches every word ending in 'ed', and "\1" stands for the first group.
transform = jiwer.SubstituteRegexes({r"doom": r"sacr", r"\b(\w+)ed\b": r"\1"})
print(transform(sentences))
# Output: ["is the world sacr or lov?", "edibles are allegedly cultivat"]
```
```

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

### Initialize RemoveWhiteSpace

Source: https://jitsi.github.io/jiwer/reference/transforms

Constructor definition for the RemoveWhiteSpace class.

```python
__init__(replace_by_space=False)
```

```python
def __init__(self, replace_by_space: bool = False):
    """

    Args:
        replace_by_space: every white space character is replaced with a space (` `)
    """
    characters = [c for c in string.whitespace]

    if replace_by_space:
        replace_token = " "
    else:
        replace_token = ""

    super().__init__(characters, replace_token=replace_token)
```

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

### jiwer.Strip

Source: https://jitsi.github.io/jiwer/reference/transforms

Removes all leading and trailing spaces from strings.

```APIDOC
## class jiwer.Strip()

### Description
Removes all leading and trailing spaces from each string in a list.

### Usage Example
```python
import jiwer
sentences = [" this is an example ", "  hello goodbye  ", "  "]
print(jiwer.Strip()(sentences))
# Output: ['this is an example', "hello goodbye", ""]
```
```

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

### Compose Multiple Transformations

Source: https://jitsi.github.io/jiwer/reference/transforms

Chains multiple transformations into a pipeline. Ensure the final transformation is a reduction type.

```python
import jiwer

jiwer.Compose([
    jiwer.RemoveMultipleSpaces(),
    jiwer.ReduceToListOfListOfWords()
])
```

```python3
import jiwer

jiwer.Compose([
    jiwer.RemoveMultipleSpaces(),
    jiwer.ReduceToListOfListOfWords()
])
```

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

### Visualize Alignment

Source: https://jitsi.github.io/jiwer/reference/alignment

Generates a string representation of the alignment between reference and hypothesis pairs.

```python
visualize_alignment(
    output,
    show_measures=True,
    skip_correct=True,
    line_width=None,
)
```

```python
import jiwer

out = jiwer.process_words(
    ["short one here", "quite a bit of longer sentence"],
    ["shoe order one", "quite bit of an even longest sentence here"],
)

print(jiwer.visualize_alignment(out))
```

```text
=== SENTENCE 1 ===

REF:    # short one here
HYP: shoe order one    *
        I     S        D

=== SENTENCE 2 ===

REF: quite a bit of  #    #  longer sentence    #
HYP: quite * bit of an even longest sentence here
           D         I    I       S             I

=== SUMMARY ===
number of sentences: 2
substitutions=2 deletions=2 insertions=4 hits=5

mer=61.54%
wil=74.75%
wip=25.25%
wer=88.89%
```

```text
=== SENTENCE 1 ===

REF:    # short one here
HYP: shoe order one    *
        I     S        D

=== SENTENCE 2 ===

REF: quite a bit of  #    #  longer sentence    #
HYP: quite * bit of an even longest sentence here
           D         I    I       S             I
```

```text
=== SENTENCE 1 ===


```

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

### Remove whitespace with jiwer.RemoveWhiteSpace

Source: https://jitsi.github.io/jiwer/reference/transforms

Demonstrates removing all whitespace or replacing it with a single space character. Note that default removal may prevent subsequent word-based processing.

```python
import jiwer

sentences = ["this is an example", "hello world "]

print(jiwer.RemoveWhiteSpace()(sentences))
# prints: ["thisisanexample", "helloworld"]

print(jiwer.RemoveWhiteSpace(replace_by_space=True)(sentences))
# prints: ["this is an example", "hello world  "]
# note the trailing spaces
```

```python
import jiwer

sentences = ["this is an example", "hello world\t"]

print(jiwer.RemoveWhiteSpace()(sentences))
# prints: ["thisisanexample", "helloworld"]

print(jiwer.RemoveWhiteSpace(replace_by_space=True)(sentences))
# prints: ["this is an example", "hello world  "]
# note the trailing spaces
```

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

### AbstractTransform.__call__

Source: https://jitsi.github.io/jiwer/reference/transforms

Transforms one or more input strings into the desired format based on the specific implementation of the transform.

```APIDOC
## AbstractTransform.__call__(sentences)

### Description
Transforms one or more strings into a processed format. This method handles both single string inputs and lists of strings.

### Parameters
- **sentences** (Union[str, List[str]]) - Required - The strings to transform.

### Returns
- **Union[str, List[str]]** - The transformed strings.
```

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

### Compute Multiple Error Metrics

Source: https://jitsi.github.io/jiwer/usage

Calculate WER, MER, and WIL metrics simultaneously, or use process_words for more efficient batch processing.

```python
import jiwer

reference = "hello world"
hypothesis = "hello duck"

wer = jiwer.wer(reference, hypothesis)
mer = jiwer.mer(reference, hypothesis)
wil = jiwer.wil(reference, hypothesis)

# faster, because `process_words` only needs to perform the heavy lifting once:
output = jiwer.process_words(reference, hypothesis)
wer = output.wer
mer = output.mer
wil = output.wil
```

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

### visualize_error_counts(output, show_substitutions=True, show_insertions=True, show_deletions=True, top_k=None)

Source: https://jitsi.github.io/jiwer/reference/alignment

Visualizes which words or characters, and how often, were substituted, inserted, or deleted based on processed output.

```APIDOC
## visualize_error_counts

### Description
Visualizes which words (or characters), and how often, were substituted, inserted, or deleted.

### Parameters
- **output** (Union[WordOutput, CharacterOutput]) - Required - The processed output of reference and hypothesis pair(s).
- **show_substitutions** (bool) - Optional - If true, visualize substitution errors. Default: True.
- **show_insertions** (bool) - Optional - If true, visualize insertion errors. Default: True.
- **show_deletions** (bool) - Optional - If true, visualize deletion errors. Default: True.
- **top_k** (Optional[int]) - Optional - If set, only visualize the k most frequent errors. Default: None.

### Returns
- **str** - A string which visualizes the words/characters and their frequencies.

### Example
```python
import jiwer

out = jiwer.process_words(
    ["short one here", "quite a bit of longer sentence"],
    ["shoe order one", "quite bit of an even longest sentence here"],
)
print(jiwer.visualize_error_counts(out))
```
```

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

### Visualize Error Counts Implementation

Source: https://jitsi.github.io/jiwer/reference/alignment

The full implementation of the visualize_error_counts function.

```python
def visualize_error_counts(
    output: Union[WordOutput, CharacterOutput],
    show_substitutions: bool = True,
    show_insertions: bool = True,
    show_deletions: bool = True,
    top_k: Optional[int] = None,
):
    """
    Visualize which words (or characters), and how often, were substituted, inserted, or deleted.

    Args:
        output: The processed output of reference and hypothesis pair(s).
        show_substitutions: If true, visualize substitution errors.
        show_insertions: If true, visualize insertion errors.
        show_deletions: If true, visualize deletion errors.
        top_k: If set, only visualize the k most frequent errors.

    Returns:
         (str): A string which visualizes the words/characters and their frequencies.

    Example:
        The code snippet
        ```python3
        import jiwer

        out = jiwer.process_words(
            ["short one here", "quite a bit of longer sentence"],
            ["shoe order one", "quite bit of an even longest sentence here"],
        )
        print(jiwer.visualize_error_counts(out))
        ```

        will print the following:

        ```txt
        === SUBSTITUTIONS ===
        short   --> order   = 1x
        longer  --> longest = 1x

        === INSERTIONS ===
        shoe    = 1x
an even = 1x
here    = 1x

        === DELETIONS ===
here = 1x
a    = 1x
        ```
    """
    s, i, d = collect_error_counts(output)

    def build_list(errors: dict):
        if len(errors) == 0:
            return "none"

        keys = [k for k in errors.keys()]
        keys = sorted(keys, reverse=True, key=lambda k: errors[k])

        if top_k is not None:
            keys = keys[:top_k]

        # we get the maximum length of all words to nicely pad output
        ln = max(len(k) if isinstance(k, str) else max(len(e) for e in k) for k in keys)

        # here we construct the string
        build = ""

        for count, (k, v) in enumerate(
            sorted(errors.items(), key=lambda tpl: tpl[1], reverse=True)
        ):
            if top_k is not None and count >= top_k:
                break

            if isinstance(k, tuple):
                build += f"{k[0]: <{ln}} --> {k[1]:<{ln}} = {v}x\n"
            else:
                build += f"{k:<{ln}} = {v}x\n"

        return build

    output = ""

    if show_substitutions:
        if output != "":
            output += "\n"
        output += "=== SUBSTITUTIONS ===\n"
        output += build_list(s)

    if show_insertions:
        if output != "":
            output += "\n"
        output += "=== INSERTIONS ===\n"
        output += build_list(i)

    if show_deletions:
        if output != "":
            output += "\n"
        output += "=== DELETIONS ===\n"
        output += build_list(d)

    if output[-1:] == "\n":
        output = output[:-1]

    return output
```

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

### ToUpperCase

Source: https://jitsi.github.io/jiwer/reference/transforms

A transformation class that converts every character in a list of strings to uppercase.

```APIDOC
## ToUpperCase

### Description
Converts every character in the input strings to uppercase.

### Usage
```python
import jiwer
sentences = ["You're amazing"]
print(jiwer.ToUpperCase()(sentences))
# prints: ["YOU'RE AMAZING"]
```
```

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

### wil(reference, hypothesis, reference_transform, hypothesis_transform)

Source: https://jitsi.github.io/jiwer/reference/measures

Calculates the word information lost (WIL) between one or more reference and hypothesis sentences.

```APIDOC
## wil(reference, hypothesis, reference_transform, hypothesis_transform)

### Description
Calculates the word information lost (WIL) between one or more reference and hypothesis sentences.

### Parameters
- **reference** (Union[str, List[str]]) - Optional - The reference sentence(s). Default: None
- **hypothesis** (Union[str, List[str]]) - Optional - The hypothesis sentence(s). Default: None
- **reference_transform** (Union[Compose, AbstractTransform]) - Optional - The transformation(s) to apply to the reference string(s). Default: wer_default
- **hypothesis_transform** (Union[Compose, AbstractTransform]) - Optional - The transformation(s) to apply to the hypothesis string(s). Default: wer_default

### Returns
- **float** - The word information lost of the given reference and hypothesis sentence(s).
```

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

### Visualize Error Counts

Source: https://jitsi.github.io/jiwer/usage

List frequencies of substitutions, insertions, and deletions.

```python
import jiwer

out = jiwer.process_words(
    ["short one here", "quite a bit of longer sentence"],
    ["shoe order one", "quite bit of an even longest sentence here"],
)

print(jiwer.visualize_error_counts(out))
```

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

### Calculate Word Information Lost (WIL)

Source: https://jitsi.github.io/jiwer/reference/measures

Computes the word information lost between reference and hypothesis sentences using optional transformations.

```python
wil(
    reference=None,
    hypothesis=None,
    reference_transform=wer_default,
    hypothesis_transform=wer_default,
)
```

```python
def wil(
    reference: Union[str, List[str]] = None,
    hypothesis: Union[str, List[str]] = None,
    reference_transform: Union[tr.Compose, tr.AbstractTransform] = wer_default,
    hypothesis_transform: Union[tr.Compose, tr.AbstractTransform] = wer_default,
) -> float:
    """
    Calculate the word information lost (WIL) between one or more reference and
    hypothesis sentences.

    Args:
        reference: The reference sentence(s)
        hypothesis: The hypothesis sentence(s)
        reference_transform: The transformation(s) to apply to the reference string(s)
        hypothesis_transform: The transformation(s) to apply to the hypothesis string(s)

    Returns:
        (float): The word information lost of the given reference and
                 hypothesis sentence(s).
    """
    output = process_words(
        reference, hypothesis, reference_transform, hypothesis_transform
    )

    return output.wil
```

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

### Expand English Contractions with jiwer

Source: https://jitsi.github.io/jiwer/reference/transforms

Expands common English contractions in a list of strings to their full forms.

```python
import jiwer

sentences = ["she'll make sure you can't make it", "let's party!"]

print(jiwer.ExpandCommonEnglishContractions()(sentences))
# prints: ["she will make sure you can not make it", "let us party!"]
```

```python
        ```python
        import jiwer

        sentences = ["she'll make sure you can't make it", "let's party!"]

        print(jiwer.ExpandCommonEnglishContractions()(sentences))
        # prints: ["she will make sure you can not make it", "let us party!"]
        ```
```

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

### Calculate word metrics in process_words

Source: https://jitsi.github.io/jiwer/reference/process

Computes error metrics including WER, MER, and WIL based on alignment tags and sentence lengths.

```python
            # Update counts
            if tag == "equal":
                hits += i2 - i1
            elif tag == "replace":
                subs += i2 - i1
            elif tag == "delete":
                dels += i2 - i1
            elif tag == "insert":
                ins += j2 - j1

        # Update global counts
        num_hits += hits
        num_substitutions += subs
        num_deletions += dels
        num_insertions += ins
        num_rf_words += len(reference_sentence)
        num_hp_words += len(hypothesis_sentence)
        alignments.append(sentence_op_chunks)

    # Compute all measures
    S, D, I, H = num_substitutions, num_deletions, num_insertions, num_hits

    # special edge-case for empty references
    if num_rf_words == 0:
        wer = num_insertions

        # if the reference was silence and this is correctly predicted,
        # there is no error and all information is preserved
        if num_hp_words == 0:
            mer = 0
            wip = 1
        else:
            mer = 1
            wip = 0

    else:
        wer = float(S + D + I) / float(H + S + D)
        mer = float(S + D + I) / float(H + S + D + I)

        # there is an edge-case when hypothesis is empty
        if num_hp_words >= 1:
            wip = (float(H) / num_rf_words) * (float(H) / num_hp_words)
        else:
            wip = 0

    wil = 1 - wip

    # return all output
    return WordOutput(
        references=ref_transformed,
        hypotheses=hyp_transformed,
        alignments=alignments,
        wer=wer,
        mer=mer,
        wil=wil,
        wip=wip,
        hits=num_hits,
        substitutions=num_substitutions,
        insertions=num_insertions,
        deletions=num_deletions,
    )
```

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

### WER Standardize Transformation

Source: https://jitsi.github.io/jiwer/reference/transformations

Standardizes strings by lowercasing, expanding contractions, and removing non-words before applying default word-based transformations.

```python
wer_standardize = Compose(
    [
        ToLowerCase(),
        ExpandCommonEnglishContractions(),
        RemoveKaldiNonWords(),
        RemoveWhiteSpace(replace_by_space=True),
        RemoveMultipleSpaces(),
        Strip(),
        ReduceToListOfListOfWords(),
    ]
)
```

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

### WER Default Transformation

Source: https://jitsi.github.io/jiwer/reference/transformations

The default transformation for process_words, which removes extra whitespace and converts strings into lists of word lists.

```python
wer_default = Compose(
    [
        RemoveMultipleSpaces(),
        Strip(),
        ReduceToListOfListOfWords(),
    ]
)
```

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

### Substitute whole words using SubstituteWords

Source: https://jitsi.github.io/jiwer/reference/transforms

Replaces specific words in a string, ensuring only whole words are matched.

```python
import jiwer

sentences = ["you're pretty", "your book", "foobar"]

print(jiwer.SubstituteWords({"pretty": "awesome", "you": "i", "'re": " am", 'foo': 'bar'})(sentences))
```

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

### ToLowerCase

Source: https://jitsi.github.io/jiwer/reference/transforms

A transformation class that converts every character in a list of strings to lowercase.

```APIDOC
## ToLowerCase

### Description
Converts every character in the input strings to lowercase.

### Usage
```python
import jiwer
sentences = ["You're PRETTY"]
print(jiwer.ToLowerCase()(sentences))
# prints: ["you're pretty"]
```
```

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

### Convert text to uppercase using ToUpperCase

Source: https://jitsi.github.io/jiwer/reference/transforms

Transforms all characters in a list of strings to uppercase.

```python
import jiwer

sentences = ["You're amazing"]

print(jiwer.ToUpperCase()(sentences))

# prints: ["YOU'RE AMAZING"]
```

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

### Compose Class Definition

Source: https://jitsi.github.io/jiwer/reference/transforms

Internal implementation of the Compose class showing the transformation chaining logic.

```python
class Compose(object):
    """
    Chain multiple transformations back-to-back to create a pipeline combining multiple
    transformations.

    Note that each transformation needs to end with either `ReduceToListOfListOfWords`
    or `ReduceToListOfListOfChars`, depending on whether word error rate,
    or character error rate is desired.

    Example:
        ```python3
        import jiwer

        jiwer.Compose([
            jiwer.RemoveMultipleSpaces(),
            jiwer.ReduceToListOfListOfWords()
        ])
        ```
    """

    def __init__(self, transforms: List[AbstractTransform]):
        """

        Args:
            transforms: The list of transformations to chain.
        """
        self.transforms = transforms

    def __call__(self, text):
        for tr in self.transforms:
            text = tr(text)

        return text
```

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

### SubstituteWords

Source: https://jitsi.github.io/jiwer/reference/transforms

A transform class used to replace specific whole words with other words in a string.

```APIDOC
## SubstituteWords

### Description
Replaces specific whole words within a string based on a provided mapping. Only whole words are matched; substrings are ignored.

### Constructor
`SubstituteWords(substitutions: Mapping[str, str])`

### Parameters
- **substitutions** (Mapping[str, str]) - Required - A mapping where keys are the words to find and values are the replacement words.
```

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

### Call process_characters Function

Source: https://jitsi.github.io/jiwer/reference/process

Calculates character-level metrics using specified reference and hypothesis transformations.

```python
process_characters(
    reference,
    hypothesis,
    reference_transform=cer_default,
    hypothesis_transform=cer_default,
)
```

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

### ReduceToSingleSentence

Source: https://jitsi.github.io/jiwer/reference/transforms

Transforms multiple sentences into a single sentence by joining them with a specified delimiter.

```APIDOC
## Class: ReduceToSingleSentence

### Description
Transforms multiple sentences into a single sentence. This is useful when the number of reference and hypothesis sentences differ, allowing for minimal alignment.

### Constructor
`ReduceToSingleSentence(word_delimiter: str = " ")`

### Parameters
- **word_delimiter** (str) - Optional - The character used to join words. Defaults to a space (" ").

### Usage Example
```python
import jiwer
sentences = ["hi", "this is an example"]
print(jiwer.ReduceToSingleSentence()(sentences))
# Output: ['hi this is an example']
```
```

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

### Retrieve Word Alignments

Source: https://jitsi.github.io/jiwer/usage

Extract alignment chunks between reference and hypothesis strings.

```python
import jiwer

out = jiwer.process_words("short one here", "shoe order one")
print(out.alignments)
# [[[AlignmentChunk(type='insert', ref_start_idx=0, ref_end_idx=0, hyp_start_idx=0, hyp_end_idx=1), ...]]
```

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

### process_words(reference, hypothesis, reference_transform, hypothesis_transform)

Source: https://jitsi.github.io/jiwer/reference/process

Computes the word-level Levenshtein distance and alignment between one or more reference and hypothesis sentences.

```APIDOC
## process_words

### Description
Compute the word-level levenshtein distance and alignment between one or more reference and hypothesis sentences. Based on the result, multiple measures can be computed, such as the word error rate.

### Parameters
- **reference** (Union[str, List[str]]) - Required - The reference sentence(s).
- **hypothesis** (Union[str, List[str]]) - Required - The hypothesis sentence(s).
- **reference_transform** (Union[Compose, AbstractTransform]) - Optional - The transformation(s) to apply to the reference string(s). Default: wer_default.
- **hypothesis_transform** (Union[Compose, AbstractTransform]) - Optional - The transformation(s) to apply to the hypothesis string(s). Default: wer_default.

### Returns
- **WordOutput** - The processed reference and hypothesis sentences.

### Raises
- **ValueError** - If one or more references are empty strings.
- **ValueError** - If after applying transforms, reference and hypothesis lengths don't match.
```

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

### Visualize Error Counts Function Signature

Source: https://jitsi.github.io/jiwer/reference/alignment

The function signature for visualizing error counts in jiwer.

```python
visualize_error_counts(
    output,
    show_substitutions=True,
    show_insertions=True,
    show_deletions=True,
    top_k=None,
)
```

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

### ReduceToSingleSentence Usage

Source: https://jitsi.github.io/jiwer/reference/transforms

Combines multiple sentences into one. Note that this operation can affect alignment invariance.

```python
import jiwer

sentences = ["hi", "this is an example"]

print(jiwer.ReduceToSingleSentence()(sentences))
# prints: ['hi this is an example']
```

```python
class ReduceToSingleSentence(AbstractTransform):
    """
    Transforms multiple sentences into a single sentence.
    This operation can be useful when the number of reference and hypothesis sentences
    differ, and you want to do a minimal alignment over these lists.
    Note that this creates an invariance: `wer([a, b], [a, b])` might not be equal to
    `wer([b, a], [b, a])`.

    Example:
        ```python3
        import jiwer

        sentences = ["hi", "this is an example"]

        print(jiwer.ReduceToSingleSentence()(sentences))
        # prints: ['hi this is an example']
        ```
    """

    def __init__(self, word_delimiter: str = " "):
        """
        :param word_delimiter: the character which delimits words. Default is ` ` (space).
        """
        self.word_delimiter = word_delimiter

    def process_string(self, s: str):
        return s

    def process_list(self, inp: List[str]):
        filtered_inp = [i for i in inp if len(i) >= 1]

        if len(filtered_inp) == 0:
            return []
        else:
            return ["{}".format(self.word_delimiter).join(filtered_inp)]
```

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

### ToLowerCase

Source: https://jitsi.github.io/jiwer/reference/transforms

A transform class that converts all characters in a string to lowercase.

```APIDOC
## ToLowerCase

### Description
Converts every character in the input string or list of strings into lowercase.
```

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

### process_characters

Source: https://jitsi.github.io/jiwer/reference/process

Calculates character-level metrics between reference and hypothesis strings.

```APIDOC
## process_characters

### Description
Calculates the character-level levenshtein distance and associated metrics between a reference and a hypothesis string.

### Signature
`process_characters(reference, hypothesis, reference_transform=cer_default, hypothesis_transform=cer_default)`

### Parameters
- **reference** (str) - The reference string.
- **hypothesis** (str) - The hypothesis string.
- **reference_transform** (callable, optional) - Transformation function applied to the reference string. Defaults to `cer_default`.
- **hypothesis_transform** (callable, optional) - Transformation function applied to the hypothesis string. Defaults to `cer_default`.
```

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

### RemoveEmptyStrings Usage

Source: https://jitsi.github.io/jiwer/reference/transforms

Filters out empty or whitespace-only strings from a list.

```python
import jiwer

sentences = ["", "this is an example", " ",  "                "]

print(jiwer.RemoveEmptyStrings()(sentences))
# prints: ['this is an example']
```

```python
class RemoveEmptyStrings(AbstractTransform):
    """
    Remove empty strings from a list of strings.

    Example:
        ```python
        import jiwer

        sentences = ["", "this is an example", " ",  "                "]

        print(jiwer.RemoveEmptyStrings()(sentences))
        # prints: ['this is an example']
        ```
    """

    def process_string(self, s: str):
        return s.strip()

    def process_list(self, inp: List[str]):
        return [s for s in inp if self.process_string(s) != ""]
```

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

### Convert text to lowercase using ToLowerCase

Source: https://jitsi.github.io/jiwer/reference/transforms

Transforms all characters in a list of strings to lowercase.

```python
import jiwer

sentences = ["You're PRETTY"]

print(jiwer.ToLowerCase()(sentences))

# prints: ["you're pretty"]
```

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

### Define AbstractTransform class

Source: https://jitsi.github.io/jiwer/reference/transforms

The base class for all transformations, requiring implementation of process_string.

```python
class AbstractTransform(object):
    """
    The base class of a Transform.
    """

    def __call__(self, sentences: Union[str, List[str]]):
        """
        Transforms one or more strings.

        Args:
            sentences: The strings to transform.

        Returns:
            (Union[str, List[str]]): The transformed strings.

        """
        if isinstance(sentences, str):
            return self.process_string(sentences)
        elif isinstance(sentences, list):
            return self.process_list(sentences)
        else:
            raise ValueError(
                "input {} was expected to be a string or list of strings".format(
                    sentences
                )
            )

    def process_string(self, s: str):
        raise NotImplementedError()

    def process_list(self, inp: List[str]):
        return [self.process_string(s) for s in inp]
```

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

### Invoke __call__ method

Source: https://jitsi.github.io/jiwer/reference/transforms

Method signature for transforming strings or lists of strings.

```python
__call__(sentences)
```

```python
def __call__(self, sentences: Union[str, List[str]]):
    """
    Transforms one or more strings.

    Args:
        sentences: The strings to transform.

    Returns:
        (Union[str, List[str]]): The transformed strings.

    """
    if isinstance(sentences, str):
        return self.process_string(sentences)
    elif isinstance(sentences, list):
        return self.process_list(sentences)
    else:
        raise ValueError(
            "input {} was expected to be a string or list of strings".format(
                sentences
            )
        )
```

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

### Calculate Word Error Rate (WER)

Source: https://jitsi.github.io/jiwer/reference/measures

Computes the word error rate between reference and hypothesis sentences using optional transformations.

```python
wer(
    reference=None,
    hypothesis=None,
    reference_transform=wer_default,
    hypothesis_transform=wer_default,
)
```

```python
def wer(
    reference: Union[str, List[str]] = None,
    hypothesis: Union[str, List[str]] = None,
    reference_transform: Union[tr.Compose, tr.AbstractTransform] = wer_default,
    hypothesis_transform: Union[tr.Compose, tr.AbstractTransform] = wer_default,
) -> float:
    """
    Calculate the word error rate (WER) between one or more reference and
    hypothesis sentences.

    Args:
        reference: The reference sentence(s)
        hypothesis: The hypothesis sentence(s)
        reference_transform: The transformation(s) to apply to the reference string(s)
        hypothesis_transform: The transformation(s) to apply to the hypothesis string(s)

    Returns:
        (float): The word error rate of the given reference and
                 hypothesis sentence(s).
    """
    output = process_words(
        reference, hypothesis, reference_transform, hypothesis_transform
    )

    return output.wer
```

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

### ToLowerCase Transform Usage

Source: https://jitsi.github.io/jiwer/reference/transforms

Converts all characters in the input strings to lowercase.

```python
import jiwer

sentences = ["You're PRETTY"]

print(jiwer.ToLowerCase()(sentences))
```

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

### ExpandCommonEnglishContractions

Source: https://jitsi.github.io/jiwer/reference/transforms

A transformation class that replaces common English contractions with their expanded forms (e.g., 'let's' to 'let us').

```APIDOC
## ExpandCommonEnglishContractions

### Description
Replaces common contractions in a string or list of strings with their expanded forms.

### Usage
```python
import jiwer
sentences = ["she'll make sure you can't make it", "let's party!"]
print(jiwer.ExpandCommonEnglishContractions()(sentences))
# Output: ["she will make sure you can not make it", "let us party!"]
```
```

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

### Strip leading and trailing spaces

Source: https://jitsi.github.io/jiwer/reference/transforms

Removes leading and trailing whitespace from strings. Be aware that this may result in empty strings if the input consists only of whitespace.

```python
import jiwer

sentences = [" this is an example ", "  hello goodbye  ", "  "]

print(jiwer.Strip()(sentences))
# prints: ['this is an example', "hello goodbye", ""]
# note that there is an empty string left behind which might need to be cleaned up
```

```python
class Strip(AbstractTransform):
    """
    Removes all leading and trailing spaces.

    Example:
        ```python
        import jiwer

        sentences = [" this is an example ", "  hello goodbye  ", "  "]

        print(jiwer.Strip()(sentences))
        # prints: ['this is an example', "hello goodbye", ""]
        # note that there is an empty string left behind which might need to be cleaned up
        ```
    """

    def process_string(self, s: str):
        return s.strip()
```

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

### ReduceToListOfListOfWords Usage

Source: https://jitsi.github.io/jiwer/reference/transforms

Converts input sentences into a list of word lists for word-level edit operations. Empty strings are removed from the output.

```python
import jiwer

sentences = ["hi", "this is an example"]

print(jiwer.ReduceToListOfListOfWords()(sentences))
# prints: [['hi'], ['this', 'is', 'an, 'example']]
```

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

### CER Default Transformation

Source: https://jitsi.github.io/jiwer/reference/transformations

The default transformation for process_characters, which removes leading/trailing whitespace and converts strings into lists of character lists.

```python
cer_default = Compose(
    [Strip(), ReduceToListOfListOfChars()]
)
```
Tokens:
Raw