pypar 0.0.6

Python phoneme alignment representation

Python phoneme alignment representation

pip install pypar

Word and phoneme alignment representation for speech tasks. This repo does not perform forced word or phoneme alignment, but provides an interface for working with the resulting alignment of a forced aligner, such as pyfoal, or a manual alignment.

Table of contents

• Usage
  • Creating alignments
  • Accessing words and phonemes
  • Saving alignments
• Application programming interface (API)
  • pypar.Alignment
    • pypar.Alignment.__init__
    • pypar.Alignment.__add__
    • pypar.Alignment.__eq__
    • pypar.Alignment.__getitem__
    • pypar.Alignment.__len__
    • pypar.Alignment.__str__
    • pypar.Alignment.duration
    • pypar.Alignment.end
    • pypar.Alignment.find
    • pypar.Alignment.framewise_phoneme_indices
    • pypar.Alignment.phonemes
    • pypar.Alignment.phoneme_at_time
    • pypar.Alignment.phoneme_bounds
    • pypar.Alignment.save
    • pypar.Alignment.start
    • pypar.Alignment.update
    • pypar.Alignment.words
    • pypar.Alignment.word_bounds
  • pypar.Phoneme
    • pypar.Phoneme.__init__
    • pypar.Phoneme.__eq__
    • pypar.Phoneme.__str__
    • pypar.Phoneme.duration
    • pypar.Phoneme.end
    • pypar.Phoneme.start
  • pypar.Word
    • pypar.Word.__init__
    • pypar.Word.__eq__
    • pypar.Word.__getitem__
    • pypar.Word.__len__
    • pypar.Word.__str__
    • pypar.Word.duration
    • pypar.Word.end
    • pypar.Word.phoneme_at_time
    • pypar.Word.start
• Tests

Usage

Creating alignments

If you already have the alignment saved to a json, mlf, or TextGrid file, pass the name of the file. Valid examples of each format can be found in test/assets/.

alignment = pypar.Alignment(file)

Alignments can be created manually from Word and Phoneme objects. Start and end times are given in seconds.

# Create a word from phonemes
word = pypar.Word(
    'THE',
    [pypar.Phoneme('DH', 0., .03), pypar.Phoneme('AH0', .03, .06)])

# Create a silence
silence = pypar.Word(pypar.SILENCE, pypar.Phoneme(pypar.SILENCE, .06, .16))

# Make an alignment
alignment = pypar.Alignment([word, silence])

You can create a new alignment from existing alignments via slicing and concatenation.

# Slice
first_two_words = alignment[:2]

# Concatenate
alignment_with_repeat = first_two_words + alignment

Accessing words and phonemes

To retrieve a list of words in the alignment, use alignment.words(). To retrieve a list of phonemes, use alignment.phonemes(). The Alignment, Word, and Phoneme objects all define .start(), .end(), and .duration() methods, which return the start time, end time, and duration, respectively. All times are given in units of seconds. These objects also define equality checks via ==, casting to string with str(), and iteration as follows.

# Iterate over words
for word in alignment:

    # Access start and end times
    assert word.duration() == word.end() - word.start()

    # Iterate over phonemes in word
    for phoneme in word:

        # Access string representation
        assert isinstance(str(phoneme), str)

To access a word or phoneme at a specific time, pass the time in seconds to alignment.word_at_time or alignment.phoneme_at_time.

To retrieve the frame indices of the start and end of a word or phoneme, pass the audio sampling rate and hopsize (in samples) to alignment.word_bounds or alignment.phoneme_bounds.

Saving alignments

To save an alignment to disk, use alignment.save(file), where file is the desired filename. pypar currently supports saving as a json or TextGrid file.

Application programming interface (API)

pypar.Alignment

pypar.Alignment.__init__

def __init__(
    self,
    alignment: Union[str, bytes, os.PathLike, List[pypar.Word], dict]
) -> None:
    """Create alignment

    Arguments
        alignment
            The filename, list of words, or json dict of the alignment
    """

pypar.Alignment.__add__

def __add__(self, other):
    """Add alignments by concatenation

    Arguments
        other
            The alignment to compare to

    Returns
        The concatenated alignment
    """

pypar.Alignment.__eq__

def __eq__(self, other) -> bool:
    """Equality comparison for alignments

    Arguments
        other
            The alignment to compare to

    Returns
        Whether the alignments are equal
    """

pypar.Alignment.__getitem__

def __getitem__(self, idx: Union[int, slice]) -> pypar.Word:
    """Retrieve the idxth word

    Arguments
        idx
            The index of the word to retrieve

    Returns
        The word at index idx
    """

pypar.Alignment.__len__

def __len__(self) -> int:
    """Retrieve the number of words

    Returns
        The number of words in the alignment
    """

pypar.Alignment.__str__

def __str__(self) -> str:
    """Retrieve the text

    Returns
        The words in the alignment separated by spaces
    """

pypar.Alignment.duration

def duration(self) -> float:
    """Retrieve the duration of the alignment in seconds

    Returns
        The duration in seconds
    """

pypar.Alignment.end

def end(self) -> float:
    """Retrieve the end time of the alignment in seconds

    Returns
        The end time in seconds
    """

pypar.Alignment.framewise_phoneme_indices

def framewise_phoneme_indices(
    self,
    phoneme_map: Dict[str, int],
    hopsize: float,
    times: Optional[List[float]] = None
) -> List[int]:
    """Convert alignment to phoneme indices at regular temporal interval

    Arguments
        phoneme_map
            Mapping from phonemes to indices
        hopsize
            Temporal interval between frames in seconds
        times
            Specified times in seconds to sample phonemes
    """

pypar.Alignment.find

def find(self, words: str) -> int:
    """Find the words in the alignment

    Arguments
        words
            The words to find

    Returns
        The index of the start of the words or -1 if not found
    """

pypar.Alignment.phonemes

def phonemes(self) -> List[pypar.Phoneme]:
    """Retrieve the phonemes in the alignment

    Returns
        The phonemes in the alignment
    """

pypar.Alignment.phoneme_at_time

def phoneme_at_time(self, time: float) -> Optional[pypar.Phoneme]:
    """Retrieve the phoneme spoken at specified time

    Arguments
        time
            Time in seconds

    Returns
        The phoneme at the given time (or None if time is out of bounds)
    """

pypar.Alignment.phoneme_bounds

def phoneme_bounds(
    self,
    sample_rate: int,
    hopsize: int = 1
) -> List[Tuple[int, int]]:
    """Retrieve the start and end frame index of each phoneme

    Arguments
        sample_rate
            The audio sampling rate
        hopsize
            The number of samples between successive frames

    Returns
        The start and end indices of the phonemes
    """

pypar.Alignment.save

def save(self, filename: Union[str, bytes, os.PathLike]) -> None:
    """Save alignment to json

    Arguments
        filename
            The location on disk to save the phoneme alignment json
    """

pypar.Alignment.start

def start(self) -> float:
    """Retrieve the start time of the alignment in seconds

    Returns
        The start time in seconds
    """

pypar.Alignment.update

def update(
    self,
    idx: int = 0,
    durations: Optional[List[float]] = None,
    start: Optional[float] = None
) -> None:
    """Update alignment starting from phoneme index idx

    Arguments
        idx
            The index of the first phoneme whose duration is being updated
        durations
            The new phoneme durations, starting from idx
        start
            The start time of the alignment
    """

pypar.Alignment.words

def words(self) -> List[pypar.Word]:
    """Retrieve the words in the alignment

    Returns
        The words in the alignment
    """

pypar.Alignment.word_bounds

def word_at_time(self, time: float) -> Optional[pypar.Word]:
    """Retrieve the word spoken at specified time

    Arguments
        time
            Time in seconds

    Returns
        The word spoken at the specified time
    """

pypar.Phoneme

pypar.Phoneme.__init__

def __init__(self, phoneme: str, start: float, end: float) -> None:
    """Create phoneme

    Arguments
        phoneme
            The phoneme
        start
            The start time in seconds
        end
            The end time in seconds
    """

pypar.Phoneme.__eq__

def __eq__(self, other) -> bool:
    """Equality comparison for phonemes

    Arguments
        other
            The phoneme to compare to

    Returns
        Whether the phonemes are equal
    """

pypar.Phoneme.__str__

def __str__(self) -> str:
    """Retrieve the phoneme text

    Returns
        The phoneme
    """

pypar.Phoneme.duration

def duration(self) -> float:
    """Retrieve the phoneme duration

    Returns
        The duration in seconds
    """

pypar.Phoneme.end

def end(self) -> float:
    """Retrieve the end time of the phoneme in seconds

    Returns
        The end time in seconds
    """

pypar.Phoneme.start

def start(self) -> float:
    """Retrieve the start time of the phoneme in seconds

    Returns
        The start time in seconds
    """

pypar.Word

pypar.Word.__init__

def __init__(self, word: str, phonemes: List[pypar.Phoneme]) -> None:
    """Create word

    Arguments
        word
            The word
        phonemes
            The phonemes in the word
    """

pypar.Word.__eq__

def __eq__(self, other) -> bool:
    """Equality comparison for words

    Arguments
        other
            The word to compare to

    Returns
        Whether the words are the same
    """

pypar.Word.__getitem__

def __getitem__(self, idx: int) -> pypar.Phoneme:
    """Retrieve the idxth phoneme

    Arguments
        idx
            The index of the phoneme to retrieve

    Returns
        The phoneme at index idx
    """

pypar.Word.__len__

def __len__(self) -> int:
    """Retrieve the number of phonemes

    Returns
        The number of phonemes
    """

pypar.Word.__str__

def __str__(self) -> str:
    """Retrieve the word text

    Returns
        The word text
    """

pypar.Word.duration

def duration(self) -> float:
    """Retrieve the word duration in seconds

    Returns
        The duration in seconds
    """

pypar.Word.end

def end(self) -> float:
    """Retrieve the end time of the word in seconds

    Returns
        The end time in seconds
    """

pypar.Word.phoneme_at_time

def phoneme_at_time(self, time: float) -> Optional[pypar.Phoneme]:
    """Retrieve the phoneme at the specified time

    Arguments
        time
            Time in seconds

    Returns
        The phoneme at the given time (or None if time is out of bounds)
    """

pypar.Word.start

    def start(self) -> float:
        """Retrieve the start time of the word in seconds

        Returns
            The start time in seconds
        """

Tests

Tests can be run as follows.

pip install pytest
pytest