Merge pull request #8 from teddybear082/feature_text_preprocessing

app/config.py

@@ -41,7 +41,12 @@ class Config:
     VOICES_DIR = os.environ.get('POCKET_TTS_VOICES_DIR', None)
 
     # Streaming default
-    STREAM_DEFAULT = os.environ.get('POCKET_TTS_STREAM_DEFAULT', 'true').lower() == 'true'
+    STREAM_DEFAULT = os.environ.get('POCKET_TTS_STREAM_DEFAULT', 'false').lower() == 'true'
+
+    # Text preprocessing default
+    TEXT_PREPROCESS_DEFAULT = (
+        os.environ.get('POCKET_TTS_TEXT_PREPROCESS_DEFAULT', 'false').lower() == 'true'
+    )
 
     # Docker detection
     @staticmethod

app/routes.py

@@ -22,6 +22,7 @@ from app.services.audio import (
     validate_format,
     write_wav_header,
 )
+from app.services.preprocess import TextPreprocessor
 from app.services.tts import get_tts_service
 
 logger = get_logger('routes')
@@ -29,6 +30,18 @@ logger = get_logger('routes')
 # Create blueprint
 api = Blueprint('api', __name__)
 
+# Create text preprocessor instance, some options changed from defaults
+text_preprocessor = TextPreprocessor(
+    remove_urls=False,
+    remove_emails=False,
+    remove_html=True,
+    remove_hashtags=True,
+    remove_mentions=False,
+    remove_punctuation=False,
+    remove_stopwords=False,
+    remove_extra_whitespace=False,
+)
+
 
 @api.route('/')
 def home():
@@ -147,7 +160,13 @@ def generate_speech():
                 target_format,
             )
             use_streaming = False
-
+        # Check if text preprocessing should be used
+        use_text_preprocess = current_app.config.get('TEXT_PREPROCESS_DEFAULT', False)
+        # Preprocess text
+        if use_text_preprocess:
+            # logger.info(f'Preprocessing text: {text}')
+            text = text_preprocessor.process(text)
+            # logger.info(f'Preprocessed text: {text}')
         if use_streaming:
             return _stream_audio(tts, voice_state, text, target_format)
         return _generate_file(tts, voice_state, text, target_format)

app/services/preprocess.py

@@ -0,0 +1,1093 @@
+"""
+Adapted and supplemented from origional at https://github.com/KittenML/KittenTTS/blob/main/kittentts/preprocess.py
+See license at: https://github.com/KittenML/KittenTTS/blob/main/LICENSE (Apache 2.0)
+"""
+
+import re
+import unicodedata
+
+# ─────────────────────────────────────────────
+# Number → Words conversion
+# ─────────────────────────────────────────────
+
+_ONES = [
+    '',
+    'one',
+    'two',
+    'three',
+    'four',
+    'five',
+    'six',
+    'seven',
+    'eight',
+    'nine',
+    'ten',
+    'eleven',
+    'twelve',
+    'thirteen',
+    'fourteen',
+    'fifteen',
+    'sixteen',
+    'seventeen',
+    'eighteen',
+    'nineteen',
+]
+_TENS = ['', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety']
+_SCALE = ['', 'thousand', 'million', 'billion', 'trillion']
+
+_ORDINAL_EXCEPTIONS = {
+    'one': 'first',
+    'two': 'second',
+    'three': 'third',
+    'four': 'fourth',
+    'five': 'fifth',
+    'six': 'sixth',
+    'seven': 'seventh',
+    'eight': 'eighth',
+    'nine': 'ninth',
+    'twelve': 'twelfth',
+}
+
+_CURRENCY_SYMBOLS = {
+    '$': 'dollar',
+    '€': 'euro',
+    '£': 'pound',
+    '¥': 'yen',
+    '₹': 'rupee',
+    '₩': 'won',
+    '₿': 'bitcoin',
+}
+
+_CURRENCY_SCALE_MAP = {
+    'K': 'thousand',
+    'M': 'million',
+    'B': 'billion',
+    'T': 'trillion',
+    'thousand': 'thousand',
+    'million': 'million',
+    'billion': 'billion',
+    'trillion': 'trillion',
+}
+
+_ROMAN = [
+    (1000, 'M'),
+    (900, 'CM'),
+    (500, 'D'),
+    (400, 'CD'),
+    (100, 'C'),
+    (90, 'XC'),
+    (50, 'L'),
+    (40, 'XL'),
+    (10, 'X'),
+    (9, 'IX'),
+    (5, 'V'),
+    (4, 'IV'),
+    (1, 'I'),
+]
+_RE_ROMAN = re.compile(r'\b(M{0,4})(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})\b')
+
+
+def _three_digits_to_words(n: int) -> str:
+    """Convert a number 0–999 to English words."""
+    if n == 0:
+        return ''
+    parts = []
+    hundreds = n // 100
+    remainder = n % 100
+    if hundreds:
+        parts.append(f'{_ONES[hundreds]} hundred')
+    if remainder < 20:
+        if remainder:
+            parts.append(_ONES[remainder])
+    else:
+        tens_word = _TENS[remainder // 10]
+        ones_word = _ONES[remainder % 10]
+        parts.append(f'{tens_word}-{ones_word}' if ones_word else tens_word)
+    return ' '.join(parts)
+
+
+def number_to_words(n: int) -> str:
+    """
+    Convert an integer to its English word representation.
+
+    Examples:
+        1200      → "twelve hundred"
+        1000      → "one thousand"
+        1_000_000 → "one million"
+        -42       → "negative forty-two"
+        0         → "zero"
+    """
+    if not isinstance(n, int):
+        n = int(n)
+    if n == 0:
+        return 'zero'
+    if n < 0:
+        return f'negative {number_to_words(-n)}'
+
+    # X00–X999 read as "X hundred" (e.g. 1200 → "twelve hundred")
+    # Exclude exact multiples of 1000 (1000 → "one thousand", not "ten hundred")
+    if 100 <= n <= 9999 and n % 100 == 0 and n % 1000 != 0:
+        hundreds = n // 100
+        if hundreds < 20:
+            return f'{_ONES[hundreds]} hundred'
+
+    parts = []
+    for _i, scale in enumerate(_SCALE):
+        chunk = n % 1000
+        if chunk:
+            chunk_words = _three_digits_to_words(chunk)
+            parts.append(f'{chunk_words} {scale}'.strip() if scale else chunk_words)
+        n //= 1000
+        if n == 0:
+            break
+
+    return ' '.join(reversed(parts))
+
+
+def float_to_words(value, decimal_sep: str = 'point') -> str:
+    """
+    Convert a float (or numeric string) to words, reading decimal digits individually.
+    Accepts a string to preserve trailing zeros (e.g. "1.50" → "one point five zero").
+
+    Examples:
+        3.14   → "three point one four"
+        -0.5   → "negative zero point five"
+        "3.10" → "three point one zero"
+        1.007  → "one point zero zero seven"
+    """
+    text = value if isinstance(value, str) else f'{value}'
+    negative = text.startswith('-')
+    if negative:
+        text = text[1:]
+
+    if '.' in text:
+        int_part, dec_part = text.split('.', 1)
+        int_words = number_to_words(int(int_part)) if int_part else 'zero'
+        # Read each decimal digit individually; "0" → "zero"
+        digit_map = ['zero'] + _ONES[1:]  # index 0 → "zero"
+        dec_words = ' '.join(digit_map[int(d)] for d in dec_part)
+        result = f'{int_words} {decimal_sep} {dec_words}'
+    else:
+        result = number_to_words(int(text))
+
+    return f'negative {result}' if negative else result
+
+
+def roman_to_int(s: str) -> int:
+    """Convert a Roman numeral string to an integer."""
+    val = {'I': 1, 'V': 5, 'X': 10, 'L': 50, 'C': 100, 'D': 500, 'M': 1000}
+    result = 0
+    prev = 0
+    for ch in reversed(s.upper()):
+        curr = val[ch]
+        result += curr if curr >= prev else -curr
+        prev = curr
+    return result
+
+
+# ─────────────────────────────────────────────
+# Regex patterns
+# ─────────────────────────────────────────────
+
+_RE_URL = re.compile(r'https?://\S+|www\.\S+')
+_RE_EMAIL = re.compile(r'\b[\w.+-]+@[\w-]+\.[a-z]{2,}\b', re.IGNORECASE)
+_RE_HASHTAG = re.compile(r'#\w+')
+_RE_MENTION = re.compile(r'@\w+')
+_RE_HTML = re.compile(r'<[^>]+>')
+_RE_PUNCT = re.compile(r'[^\w\s]')
+_RE_SPACES = re.compile(r'\s+')
+_RE_AI = re.compile(r'\bAI\b')
+_RE_DOT_COM = re.compile(r'\.com\b', re.IGNORECASE)
+_RE_PLUS = re.compile(r'\+')
+_RE_AMPERSAND = re.compile(r'&')
+_RE_AT_SYMBOL = re.compile(r'@')
+_RE_NEWLINE = re.compile(r'[\r\n]+')
+_RE_TILDE = re.compile(r'~')
+
+_MONTH_MAP = {
+    'Jan': 'January',
+    'Feb': 'February',
+    'Mar': 'March',
+    'Apr': 'April',
+    'Jun': 'June',
+    'Jul': 'July',
+    'Aug': 'August',
+    'Sep': 'September',
+    'Sept': 'September',
+    'Oct': 'October',
+    'Nov': 'November',
+    'Dec': 'December',
+}
+
+# Regex looks for Title Case months followed by a period or a digit
+# We handle "May" separately because it's a common word.
+_RE_MONTHS = re.compile(r'\b(Jan|Feb|Mar|Apr|Jun|Jul|Aug|Sep|Sept|Oct|Nov|Dec)\.?\b(?=\s*\d|\s*$)')
+_RE_MAY = re.compile(r'\bMay\b(?=\s*\d)')  # Only expand May if followed by a number (May 5)
+
+# Number: do NOT match a leading minus if it is immediately preceded by a letter
+# (handles "gpt-3", "gpl-3", "v-2" etc.)
+_RE_NUMBER = re.compile(r'(?<![a-zA-Z])-?[\d,]+(?:\.\d+)?')
+
+# Ordinals: 1st, 2nd, 3rd, 4th … 21st, 101st …
+_RE_ORDINAL = re.compile(r'\b(\d+)(st|nd|rd|th)\b', re.IGNORECASE)
+
+# Percentages: 50%, 3.5%
+_RE_PERCENT = re.compile(r'(-?[\d,]+(?:\.\d+)?)\s*%')
+
+# Currency: $100, €1,200.50, £50, $85K, $2.5M (optional scale suffix)
+_RE_CURRENCY = re.compile(
+    r'([$€£¥₹₩₿])\s*([\d,]+(?:\.\d+)?)\s*(million|billion|trillion|thousand|[KMBT])?\b',
+    re.IGNORECASE,
+)
+
+# Time: 3:30pm, 14:00, 3:30 AM — requires 2-digit minutes so "3:0" (score) doesn't match
+_RE_TIME = re.compile(r'\b(\d{1,2}):(\d{2})(?::(\d{2}))?\s*(am|pm)?\b', re.IGNORECASE)
+
+# Ranges: 10-20, 100-200 (both sides numeric, hyphen between them)
+_RE_RANGE = re.compile(r'(?<!\w)(\d+)-(\d+)(?!\w)')
+
+# Version/model names: gpt-3, gpt-3.5, v2.0, Python-3.10, GPL-3
+# Letter(s) + hyphen + digit(s) [+ more version parts]
+_RE_MODEL_VER = re.compile(r'\b([a-zA-Z][a-zA-Z0-9]*)-(\d[\d.]*)(?=[^\d.]|$)')
+
+# Measurement units glued to numbers: 100km, 50kg, 25°C, 5GB
+_RE_UNIT = re.compile(
+    r'(\d+(?:\.\d+)?)\s*(km|kg|mg|ml|gb|mb|kb|tb|hz|khz|mhz|ghz|mph|kph|°[cCfF]|[cCfF]°|ms|ns|µs)\b',
+    re.IGNORECASE,
+)
+
+# Scale suffixes (uppercase only to avoid ambiguity): 7B, 340M, 1.5K, 2T
+# Must NOT be preceded by a letter (so 'MB' is handled by unit regex first)
+_RE_SCALE = re.compile(r'(?<![a-zA-Z])(\d+(?:\.\d+)?)\s*([KMBT])(?![a-zA-Z\d])')
+
+# Scientific notation: 1e-4, 2.5e10, 6.022E23
+_RE_SCI = re.compile(r'(?<![a-zA-Z\d])(-?\d+(?:\.\d+)?)[eE]([+-]?\d+)(?![a-zA-Z\d])')
+
+# Fractions: 1/2, 3/4, 2/3
+_RE_FRACTION = re.compile(r'\b(\d+)\s*/\s*(\d+)\b')
+
+# Decades: 80s, 90s, 1980s, 2020s (number ending in 0 followed by 's')
+_RE_DECADE = re.compile(r'\b(\d{1,3})0s\b')
+
+# Leading decimal (no digit before the dot): .5, .75
+_RE_LEAD_DEC = re.compile(r'(?<!\d)\.([\d])')
+
+
+# ─────────────────────────────────────────────
+# Expansion helpers
+# ─────────────────────────────────────────────
+def expand_abbreviations(text: str) -> str:
+    """
+    Handles specific abbreviations before lowercase normalization.
+    AI -> A.I.
+    .com -> dot com
+    """
+    # 1. AI to A.I. (Case sensitive)
+    text = _RE_AI.sub('A.I.', text)
+    # 2. .com to dot com
+    text = _RE_DOT_COM.sub(' dot com', text)
+    return text
+
+
+def expand_symbols(text: str) -> str:
+    """
+    Translates mathematical and connector symbols to words.
+    """
+    text = _RE_PLUS.sub(' plus ', text)
+    text = _RE_AMPERSAND.sub(' and ', text)
+    text = _RE_AT_SYMBOL.sub(' at ', text)
+    return text
+
+
+def _ordinal_suffix(n: int) -> str:
+    """Return the ordinal word for n (e.g. 1 → 'first', 5 → 'fifth', 21 → 'twenty-first')."""
+    word = number_to_words(n)
+    # For hyphenated compounds like "twenty-one", convert only the last part
+    if '-' in word:
+        prefix, last = word.rsplit('-', 1)
+        joiner = '-'
+    else:
+        parts = word.rsplit(' ', 1)
+        prefix, last, joiner = (parts[0], parts[1], ' ') if len(parts) == 2 else ('', parts[0], '')
+
+    # Check exception table
+    for base, ordinal in _ORDINAL_EXCEPTIONS.items():
+        if last == base:
+            last_ord = ordinal
+            break
+    else:
+        # General rule
+        if last.endswith('t'):
+            last_ord = last + 'h'
+        elif last.endswith('e'):
+            last_ord = last[:-1] + 'th'
+        else:
+            last_ord = last + 'th'
+
+    return f'{prefix}{joiner}{last_ord}' if prefix else last_ord
+
+
+def expand_ordinals(text: str) -> str:
+    """
+    Convert ordinal numbers to words.
+
+    Examples:
+        "1st place"  → "first place"
+        "2nd floor"  → "second floor"
+        "3rd base"   → "third base"
+        "21st century" → "twenty-first century"
+        "100th day"  → "one hundredth day"
+    """
+
+    def _replace(m: re.Match) -> str:
+        return _ordinal_suffix(int(m.group(1)))
+
+    return _RE_ORDINAL.sub(_replace, text)
+
+
+def expand_percentages(text: str) -> str:
+    """
+    Expand percentage expressions.
+
+    Examples:
+        "50% off"    → "fifty percent off"
+        "3.5% rate"  → "three point five percent rate"
+        "-2% change" → "negative two percent change"
+    """
+
+    def _replace(m: re.Match) -> str:
+        raw = m.group(1).replace(',', '')
+        if '.' in raw:
+            return float_to_words(float(raw)) + ' percent'
+        return number_to_words(int(raw)) + ' percent'
+
+    return _RE_PERCENT.sub(_replace, text)
+
+
+def expand_newlines(text: str) -> str:
+    """Change newlines/returns to a period and space for TTS pausing."""
+    return _RE_NEWLINE.sub('. ', text)
+
+
+def expand_tilde(text: str) -> str:
+    """Change ~ to 'about'."""
+    return _RE_TILDE.sub('about ', text)
+
+
+def expand_currency(text: str) -> str:
+    """
+    Expand currency amounts, including optional scale suffixes.
+
+    Examples:
+        "$100"      → "one hundred dollars"
+        "€1,200.50" → "twelve hundred euros and fifty cents"
+        "£9.99"     → "nine pounds and ninety-nine cents"
+        "$85K"      → "eighty five thousand dollars"
+        "$2.5M"     → "two point five million dollars"
+    """
+
+    def _replace(m: re.Match) -> str:
+        symbol = m.group(1)
+        raw = m.group(2).replace(',', '')
+        scale_suffix = m.group(3)
+        unit = _CURRENCY_SYMBOLS.get(symbol, '')
+
+        # Handle Scaled Currency ($17.5 billion or $17.5B)
+        if scale_suffix:
+            # Normalize suffix (e.g., 'B' or 'billion' -> 'billion')
+            scale_word = _CURRENCY_SCALE_MAP.get(scale_suffix.upper(), scale_suffix.lower())
+            num = float_to_words(raw) if '.' in raw else number_to_words(int(raw))
+            return f'{num} {scale_word} {unit}{"s" if unit else ""}'.strip()
+
+        # Handle Standard Currency ($17.50)
+        if '.' in raw:
+            int_part, dec_part = raw.split('.', 1)
+            dec_val = int(dec_part[:2].ljust(2, '0'))
+            int_words = number_to_words(int(int_part))
+            result = f'{int_words} {unit}s' if unit else int_words
+            if dec_val:
+                cents = number_to_words(dec_val)
+                result += f' and {cents} cent{"s" if dec_val != 1 else ""}'
+        else:
+            val = int(raw)
+            words = number_to_words(val)
+            result = f'{words} {unit}{"s" if val != 1 and unit else ""}' if unit else words
+        return result
+
+    return _RE_CURRENCY.sub(_replace, text)
+
+
+def expand_time(text: str) -> str:
+    """
+    Expand time expressions.
+
+    Examples:
+        "3:30pm"  → "three thirty pm"
+        "14:00"   → "fourteen hundred"
+        "9:05 AM" → "nine oh five am"
+        "12:00pm" → "twelve pm"
+    """
+
+    def _replace(m: re.Match) -> str:
+        h = int(m.group(1))
+        mins = int(m.group(2))
+        suffix = (' ' + m.group(4).lower()) if m.group(4) else ''
+        h_words = number_to_words(h)
+        if mins == 0:
+            return f'{h_words} hundred{suffix}' if not m.group(4) else f'{h_words}{suffix}'
+        elif mins < 10:
+            return f'{h_words} oh {number_to_words(mins)}{suffix}'
+        else:
+            return f'{h_words} {number_to_words(mins)}{suffix}'
+
+    return _RE_TIME.sub(_replace, text)
+
+
+def expand_ranges(text: str) -> str:
+    """
+    Expand numeric ranges.
+
+    Examples:
+        "10-20 items"   → "ten to twenty items"
+        "pages 100-200" → "pages one hundred to two hundred"
+        "2020-2024"     → "twenty twenty to twenty twenty-four"
+    """
+
+    def _replace(m: re.Match) -> str:
+        lo = number_to_words(int(m.group(1)))
+        hi = number_to_words(int(m.group(2)))
+        return f'{lo} to {hi}'
+
+    return _RE_RANGE.sub(_replace, text)
+
+
+def expand_model_names(text: str) -> str:
+    """
+    Normalise version/model names that use letter-hyphen-number patterns,
+    so the number is not misread as negative.
+
+    Examples:
+        "GPT-3"      → "GPT 3"
+        "gpt-3.5"    → "gpt 3.5"
+        "GPL-3"      → "GPL 3"
+        "Python-3.10"→ "Python 3.10"
+        "v2.0"       stays as "v2.0" (no hyphen — handled by number replacement)
+        "IPv6"       stays as "IPv6"
+    """
+    return _RE_MODEL_VER.sub(lambda m: f'{m.group(1)} {m.group(2)}', text)
+
+
+def expand_units(text: str) -> str:
+    """
+    Expand common measurement units glued to numbers.
+
+    Examples:
+        "100km"  → "one hundred kilometers"
+        "50kg"   → "fifty kilograms"
+        "25°C"   → "twenty-five degrees Celsius"
+        "5GB"    → "five gigabytes"
+    """
+    _unit_map = {
+        'km': 'kilometers',
+        'kg': 'kilograms',
+        'mg': 'milligrams',
+        'ml': 'milliliters',
+        'gb': 'gigabytes',
+        'mb': 'megabytes',
+        'kb': 'kilobytes',
+        'tb': 'terabytes',
+        'hz': 'hertz',
+        'khz': 'kilohertz',
+        'mhz': 'megahertz',
+        'ghz': 'gigahertz',
+        'mph': 'miles per hour',
+        'kph': 'kilometers per hour',
+        'ms': 'milliseconds',
+        'ns': 'nanoseconds',
+        'µs': 'microseconds',
+        '°c': 'degrees Celsius',
+        'c°': 'degrees Celsius',
+        '°f': 'degrees Fahrenheit',
+        'f°': 'degrees Fahrenheit',
+    }
+
+    def _replace(m: re.Match) -> str:
+        raw = m.group(1)
+        unit = m.group(2).lower()
+        expanded = _unit_map.get(unit, m.group(2))
+        num = float_to_words(float(raw)) if '.' in raw else number_to_words(int(raw))
+        return f'{num} {expanded}'
+
+    return _RE_UNIT.sub(_replace, text)
+
+
+def expand_roman_numerals(text: str, context_words: bool = True) -> str:
+    """
+    Expand Roman numerals that appear as standalone tokens (optionally
+    only when preceded by a title-like word to avoid false positives).
+
+    Examples:
+        "World War II"     → "World War two"
+        "Chapter IV"       → "Chapter four"
+        "Louis XIV"        → "Louis fourteen"
+        "mix I with V"     → left unchanged (ambiguous single letters)
+    """
+    _TITLE_WORDS = re.compile(
+        r'\b(war|chapter|part|volume|act|scene|book|section|article|'
+        r'king|queen|pope|louis|henry|edward|george|william|james|'
+        r'phase|round|level|stage|class|type|version|episode|season)\b',
+        re.IGNORECASE,
+    )
+
+    def _replace(m: re.Match) -> str:
+        roman = m.group(0)
+        if not roman.strip():
+            return roman
+        # Skip single ambiguous letters (I, V, X) unless context present
+        if len(roman) == 1 and roman in 'IVX':
+            # Only expand if preceded by a title word
+            start = m.start()
+            preceding = text[max(0, start - 30) : start]
+            if not _TITLE_WORDS.search(preceding):
+                return roman
+        try:
+            val = roman_to_int(roman)
+            if val == 0:
+                return roman
+            return number_to_words(val)
+        except Exception:
+            return roman
+
+    return _RE_ROMAN.sub(_replace, text)
+
+
+def normalize_leading_decimals(text: str) -> str:
+    """
+    Normalise bare leading-decimal floats so the number pipeline handles them.
+
+    Examples:
+        ".5 teaspoons" → "0.5 teaspoons"
+        "-.25 adjustment" → "-0.25 adjustment"
+    """
+    # Handle -.5 → -0.5 and .5 → 0.5
+    text = re.sub(r'(?<!\d)(-)\.([\d])', r'\g<1>0.\2', text)
+    return _RE_LEAD_DEC.sub(r'0.\1', text)
+
+
+def expand_scientific_notation(text: str) -> str:
+    """
+    Expand scientific-notation numbers to spoken form.
+
+    Examples:
+        "1e-4"    → "one times ten to the negative four"
+        "2.5e10"  → "two point five times ten to the ten"
+        "6.022E23"→ "six point zero two two times ten to the twenty three"
+    """
+
+    def _replace(m: re.Match) -> str:
+        coeff_raw = m.group(1)
+        exp = int(m.group(2))
+        coeff_words = (
+            float_to_words(coeff_raw) if '.' in coeff_raw else number_to_words(int(coeff_raw))
+        )
+        exp_words = number_to_words(abs(exp))
+        sign = 'negative ' if exp < 0 else ''
+        return f'{coeff_words} times ten to the {sign}{exp_words}'
+
+    return _RE_SCI.sub(_replace, text)
+
+
+def expand_scale_suffixes(text: str) -> str:
+    """
+    Expand standalone uppercase scale suffixes attached to numbers.
+
+    Examples:
+        "7B parameters" → "seven billion parameters"
+        "340M model"    → "three hundred forty million model"
+        "1.5K salary"   → "one point five thousand salary"
+        "$100K budget"  → "$100K budget"  (currency handled upstream)
+    """
+    _map = {'K': 'thousand', 'M': 'million', 'B': 'billion', 'T': 'trillion'}
+
+    def _replace(m: re.Match) -> str:
+        raw = m.group(1)
+        suffix = m.group(2)
+        scale_word = _map.get(suffix, suffix)
+        num = float_to_words(raw) if '.' in raw else number_to_words(int(raw))
+        return f'{num} {scale_word}'
+
+    return _RE_SCALE.sub(_replace, text)
+
+
+def expand_fractions(text: str) -> str:
+    """
+    Expand simple numeric fractions.
+
+    Examples:
+        "1/2 cup"  → "one half cup"
+        "3/4 mile" → "three quarters mile"
+        "2/3 done" → "two thirds done"
+        "5/8 inch" → "five eighths inch"
+    """
+
+    def _replace(m: re.Match) -> str:
+        num = int(m.group(1))
+        den = int(m.group(2))
+        if den == 0:
+            return m.group()
+        num_words = number_to_words(num)
+        if den == 2:
+            denom_word = 'half' if num == 1 else 'halves'
+        elif den == 4:
+            denom_word = 'quarter' if num == 1 else 'quarters'
+        else:
+            denom_word = _ordinal_suffix(den)
+            if num != 1:
+                denom_word += 's'
+        return f'{num_words} {denom_word}'
+
+    return _RE_FRACTION.sub(_replace, text)
+
+
+def expand_decades(text: str) -> str:
+    """
+    Expand decade expressions to words.
+
+    Examples:
+        "the 80s"    → "the eighties"
+        "the 1980s"  → "the nineteen eighties"
+        "the 2020s"  → "the twenty twenties"
+        "'90s music" → "nineties music"
+    """
+    _decade_map = {
+        0: 'hundreds',
+        1: 'tens',
+        2: 'twenties',
+        3: 'thirties',
+        4: 'forties',
+        5: 'fifties',
+        6: 'sixties',
+        7: 'seventies',
+        8: 'eighties',
+        9: 'nineties',
+    }
+
+    def _replace(m: re.Match) -> str:
+        base = int(m.group(1))  # e.g. 8 for "80s", 198 for "1980s"
+        decade_digit = base % 10
+        decade_word = _decade_map.get(decade_digit, '')
+        if base < 10:
+            return decade_word
+        century_part = base // 10  # e.g. 19 for 198
+        return f'{number_to_words(century_part)} {decade_word}'
+
+    return _RE_DECADE.sub(_replace, text)
+
+
+def expand_ip_addresses(text: str) -> str:
+    """
+    Expand IPv4 addresses to spoken digits per octet.
+
+    Examples:
+        "192.168.1.1"  → "one nine two dot one six eight dot one dot one"
+        "10.0.0.1"     → "one zero dot zero dot zero dot one"
+    """
+    _d = {
+        '0': 'zero',
+        '1': 'one',
+        '2': 'two',
+        '3': 'three',
+        '4': 'four',
+        '5': 'five',
+        '6': 'six',
+        '7': 'seven',
+        '8': 'eight',
+        '9': 'nine',
+    }
+
+    def _octet(s: str) -> str:
+        return ' '.join(_d[c] for c in s)
+
+    def _replace(m: re.Match) -> str:
+        return ' dot '.join(_octet(g) for g in m.groups())
+
+    return re.sub(r'\b(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})\b', _replace, text)
+
+
+def expand_phone_numbers(text: str) -> str:
+    """
+    Expand US phone numbers to spoken digits before range expansion claims the hyphens.
+
+    Examples:
+        "555-1234"       → "five five five one two three four"
+        "555-123-4567"   → "five five five one two three four five six seven"
+        "1-800-555-0199" → "one eight zero zero five five five zero one nine nine"
+    """
+    _d = {
+        '0': 'zero',
+        '1': 'one',
+        '2': 'two',
+        '3': 'three',
+        '4': 'four',
+        '5': 'five',
+        '6': 'six',
+        '7': 'seven',
+        '8': 'eight',
+        '9': 'nine',
+    }
+
+    def _digits(s: str) -> str:
+        return ' '.join(_d[c] for c in s)
+
+    def _join(*groups) -> str:
+        return ' '.join(_digits(g) for g in groups)
+
+    # Match longest pattern first to avoid partial matches
+    # 11-digit: 1-800-555-0199
+    text = re.sub(
+        r'(?<!\d-)(?<!\d)\b(\d{1,2})-(\d{3})-(\d{3})-(\d{4})\b(?!-\d)',
+        lambda m: _join(*m.groups()),
+        text,
+    )
+    # 10-digit: 555-123-4567
+    text = re.sub(
+        r'(?<!\d-)(?<!\d)\b(\d{3})-(\d{3})-(\d{4})\b(?!-\d)', lambda m: _join(*m.groups()), text
+    )
+    # 7-digit local: 555-1234 (not preceded or followed by digit-hyphen to avoid sub-matching)
+    text = re.sub(r'(?<!\d-)\b(\d{3})-(\d{4})\b(?!-\d)', lambda m: _join(*m.groups()), text)
+    return text
+
+
+def expand_months(text: str) -> str:
+    """
+    Expands Jan, Feb, etc. to January, February.
+    Only triggers if the abbreviation is likely a date.
+    """
+
+    def _replace(m: re.Match) -> str:
+        return _MONTH_MAP.get(m.group(1), m.group(1))
+
+    # 1. Standard abbreviations
+    text = _RE_MONTHS.sub(_replace, text)
+
+    # 2. May (Special case: only if followed by a digit)
+    text = _RE_MAY.sub('May', text)  # Essentially just ensuring it's treated as a word
+
+    return text
+
+
+# ─────────────────────────────────────────────
+# Core preprocessing functions
+# ─────────────────────────────────────────────
+
+
+def replace_numbers(text: str, replace_floats: bool = True) -> str:
+    """
+    Replace all numeric tokens with their word equivalents.
+
+    Examples:
+        "There are 1200 students" → "There are twelve hundred students"
+        "Pi is 3.14"              → "Pi is three point one four"
+        "gpt-3 rocks"             → "gpt-3 rocks"  (hyphen not treated as minus)
+    """
+
+    def _replace(m: re.Match) -> str:
+        raw = m.group().replace(',', '')
+        try:
+            if '.' in raw and replace_floats:
+                # Pass raw string so trailing zeros are preserved ("1.50" → "one point five zero")
+                return float_to_words(raw)
+            else:
+                return number_to_words(int(float(raw)))
+        except (ValueError, OverflowError):
+            return m.group()
+
+    return _RE_NUMBER.sub(_replace, text)
+
+
+def to_lowercase(text: str) -> str:
+    """Convert text to lowercase."""
+    return text.lower()
+
+
+def remove_urls(text: str, replacement: str = '') -> str:
+    """Remove URLs from text."""
+    return _RE_URL.sub(replacement, text).strip()
+
+
+def remove_emails(text: str, replacement: str = '') -> str:
+    """Remove email addresses from text."""
+    return _RE_EMAIL.sub(replacement, text).strip()
+
+
+def remove_html_tags(text: str) -> str:
+    """Strip HTML tags from text."""
+    return _RE_HTML.sub(' ', text)
+
+
+def remove_hashtags(text: str, replacement: str = '') -> str:
+    """Remove hashtags (e.g. #NLP) from text."""
+    return _RE_HASHTAG.sub(replacement, text)
+
+
+def remove_mentions(text: str, replacement: str = '') -> str:
+    """Remove @mentions from text."""
+    return _RE_MENTION.sub(replacement, text)
+
+
+def remove_punctuation(text: str) -> str:
+    """Remove all punctuation characters."""
+    return _RE_PUNCT.sub(' ', text)
+
+
+def remove_extra_whitespace(text: str) -> str:
+    """Collapse multiple whitespace characters into a single space and strip ends."""
+    return _RE_SPACES.sub(' ', text).strip()
+
+
+def normalize_unicode(text: str, form: str = 'NFC') -> str:
+    """Normalize unicode characters (NFC, NFD, NFKC, or NFKD)."""
+    return unicodedata.normalize(form, text)
+
+
+def remove_accents(text: str) -> str:
+    """Remove diacritical marks (accents) from characters."""
+    nfkd = unicodedata.normalize('NFD', text)
+    return ''.join(c for c in nfkd if unicodedata.category(c) != 'Mn')
+
+
+def expand_contractions(text: str) -> str:
+    """
+    Expand common English contractions.
+
+    Examples:
+        "don't"   → "do not"
+        "they're" → "they are"
+        "I've"    → "I have"
+    """
+    contractions = {
+        r"\bcan't\b": 'cannot',
+        r"\bwon't\b": 'will not',
+        r"\bshan't\b": 'shall not',
+        r"\bain't\b": 'is not',
+        r"\blet's\b": 'let us',
+        r"\b(\w+)n't\b": r'\1 not',
+        r"\b(\w+)'re\b": r'\1 are',
+        r"\b(\w+)'ve\b": r'\1 have',
+        r"\b(\w+)'ll\b": r'\1 will',
+        r"\b(\w+)'d\b": r'\1 would',
+        r"\b(\w+)'m\b": r'\1 am',
+        r"\bit's\b": 'it is',
+    }
+    for pattern, replacement in contractions.items():
+        text = re.sub(pattern, replacement, text, flags=re.IGNORECASE)
+    return text
+
+
+def remove_stopwords(text: str, stopwords: set | None = None) -> str:
+    """
+    Remove stopwords from text.
+
+    Args:
+        stopwords: Set of words to remove. Uses a built-in English set if None.
+    """
+    if stopwords is None:
+        stopwords = {
+            'a',
+            'an',
+            'the',
+            'and',
+            'or',
+            'but',
+            'in',
+            'on',
+            'at',
+            'to',
+            'for',
+            'of',
+            'with',
+            'by',
+            'from',
+            'is',
+            'was',
+            'are',
+            'were',
+            'be',
+            'been',
+            'being',
+            'have',
+            'has',
+            'had',
+            'do',
+            'does',
+            'did',
+            'will',
+            'would',
+            'could',
+            'should',
+            'may',
+            'might',
+            'this',
+            'that',
+            'these',
+            'those',
+            'it',
+            'its',
+            'i',
+            'me',
+            'my',
+            'we',
+            'our',
+            'you',
+            'your',
+            'he',
+            'she',
+            'him',
+            'her',
+            'they',
+            'them',
+            'their',
+        }
+    tokens = text.split()
+    return ' '.join(t for t in tokens if t.lower() not in stopwords)
+
+
+# ─────────────────────────────────────────────
+# Pipeline helper
+# ─────────────────────────────────────────────
+
+
+class TextPreprocessor:
+    """
+    Configurable preprocessing pipeline.
+
+    Usage:
+        pp = TextPreprocessor(
+            lowercase=True,
+            replace_numbers=True,
+            remove_urls=True,
+            remove_html=True,
+            remove_punctuation=True,
+        )
+        clean = pp("GPT-3 costs $0.002 per token — 50% cheaper than before!")
+        # → "gpt three costs zero dollars and zero point two cents per token fifty percent cheaper than before"
+    """
+
+    def __init__(
+        self,
+        lowercase: bool = True,
+        replace_numbers: bool = True,
+        replace_floats: bool = True,
+        expand_newlines: bool = True,
+        expand_tilde: bool = True,
+        expand_abbreviations: bool = True,
+        expand_symbols: bool = True,
+        expand_contractions: bool = True,
+        expand_model_names: bool = True,
+        expand_ordinals: bool = True,
+        expand_percentages: bool = True,
+        expand_currency: bool = True,
+        expand_time: bool = True,
+        expand_ranges: bool = True,
+        expand_units: bool = True,
+        expand_scale_suffixes: bool = True,
+        expand_scientific_notation: bool = True,
+        expand_fractions: bool = True,
+        expand_decades: bool = True,
+        expand_phone_numbers: bool = True,
+        expand_ip_addresses: bool = True,
+        normalize_leading_decimals: bool = True,
+        expand_roman_numerals: bool = False,
+        remove_urls: bool = True,
+        remove_emails: bool = True,
+        remove_html: bool = True,
+        remove_hashtags: bool = False,
+        remove_mentions: bool = False,
+        remove_punctuation: bool = True,
+        remove_stopwords: bool = False,
+        stopwords: set | None = None,
+        normalize_unicode: bool = True,
+        remove_accents: bool = False,
+        remove_extra_whitespace: bool = True,
+    ):
+        self.config = {k: v for k, v in locals().items() if k != 'self'}
+        self._stopwords = stopwords
+
+    def __call__(self, text: str) -> str:
+        return self.process(text)
+
+    def process(self, text: str) -> str:
+        cfg = self.config
+        if cfg.get('expand_abbreviations'):
+            text = expand_abbreviations(text)
+            text = expand_months(text)
+        if cfg.get('expand_newlines'):
+            text = expand_newlines(text)
+        if cfg.get('expand_symbols'):
+            text = expand_symbols(text)
+        if cfg.get('expand_tilde'):
+            text = expand_tilde(text)
+        if cfg['normalize_unicode']:
+            text = normalize_unicode(text)
+        if cfg['remove_html']:
+            text = remove_html_tags(text)
+        if cfg['remove_urls']:
+            text = remove_urls(text)
+        if cfg['remove_emails']:
+            text = remove_emails(text)
+        if cfg['remove_hashtags']:
+            text = remove_hashtags(text)
+        if cfg['remove_mentions']:
+            text = remove_mentions(text)
+        if cfg['expand_contractions']:
+            text = expand_contractions(text)
+        # IP addresses before normalize_leading_decimals (IPs contain dots before digits)
+        if cfg['expand_ip_addresses']:
+            text = expand_ip_addresses(text)
+        # Normalise bare leading decimals early so downstream regexes see "0.5" not ".5"
+        if cfg['normalize_leading_decimals']:
+            text = normalize_leading_decimals(text)
+        # Expand special forms before generic number replacement
+        if cfg['expand_currency']:
+            text = expand_currency(text)
+        if cfg['expand_percentages']:
+            text = expand_percentages(text)
+        # Scientific notation before model-name expansion (e.g. "1e-4" contains "e-4")
+        if cfg['expand_scientific_notation']:
+            text = expand_scientific_notation(text)
+        if cfg['expand_time']:
+            text = expand_time(text)
+        if cfg['expand_ordinals']:
+            text = expand_ordinals(text)
+        if cfg['expand_units']:
+            text = expand_units(text)
+        # Scale suffixes after units (units handles "MB"/"GB"; this handles bare "B"/"M")
+        if cfg['expand_scale_suffixes']:
+            text = expand_scale_suffixes(text)
+        if cfg['expand_fractions']:
+            text = expand_fractions(text)
+        if cfg['expand_decades']:
+            text = expand_decades(text)
+        # Phone numbers before ranges, otherwise NNN-NNNN is treated as a range
+        if cfg['expand_phone_numbers']:
+            text = expand_phone_numbers(text)
+        if cfg['expand_ranges']:
+            text = expand_ranges(text)
+        if cfg['expand_model_names']:
+            text = expand_model_names(text)
+        if cfg['expand_roman_numerals']:
+            text = expand_roman_numerals(text)
+        if cfg['replace_numbers']:
+            text = replace_numbers(text, replace_floats=cfg['replace_floats'])
+        if cfg['remove_accents']:
+            text = remove_accents(text)
+        if cfg['remove_punctuation']:
+            text = remove_punctuation(text)
+        if cfg['lowercase']:
+            text = to_lowercase(text)
+        if cfg['remove_stopwords']:
+            text = remove_stopwords(text, self._stopwords)
+        if cfg['remove_extra_whitespace']:
+            text = remove_extra_whitespace(text)
+
+        return text

pyproject.toml

@@ -4,12 +4,12 @@ license = {text = "MIT"}
 name = "pocket-tts-openai-server"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "2.3.0"
+version = "2.4.0"
 
 dependencies = [
   "flask>=3.0.0",
   "waitress>=3.0.0",
-  "pocket-tts>=1.1.0",
+  "pocket-tts>=1.1.1",
   "torch>=2.0.0,<=2.8.0",
   "torchaudio>=2.0.0,<=2.8.0",
   "scipy>=1.10.0",

run_pocket_tts_server.bat

@@ -62,6 +62,12 @@ set "STREAM_ARG=--stream"
 set /p "INPUT_STREAM=Enable Streaming? (Y/N) [Y]: "
 if /i "%INPUT_STREAM%"=="N" set "STREAM_ARG="
 
+:: 7. Text Preprocessing Default
+:: Defaults to ON. Only unsets if the user types 'N'.
+set "TEXT_PREPROCESS_ARG=--text-preprocess"
+set /p "INPUT_PREPROCESS=Enable Text Preprocessing? (Y/N) [Y]: "
+if /i "%INPUT_PREPROCESS%"=="N" set "TEXT_PREPROCESS_ARG="
+
 echo.
 echo ========================================================
 echo Starting Pocket TTS Server...
@@ -70,11 +76,12 @@ echo Port: %PORT%
 if defined MODEL_PATH echo Model: %MODEL_PATH%
 if defined VOICES_DIR echo Voices: %VOICES_DIR%
 if defined STREAM_ARG echo Streaming: Enabled
+if defined TEXT_PREPROCESS_ARG echo Text Preprocessing: Enabled
 echo ========================================================
 echo.
 
-:: 7. Run Command
-python server.py --host %HOST% --port %PORT% %MODEL_PATH% %VOICES_DIR_ARG% %STREAM_ARG%
+:: 8. Run Command
+python server.py --host %HOST% --port %PORT% %MODEL_PATH% %VOICES_DIR_ARG% %STREAM_ARG% %TEXT_PREPROCESS_ARG%
 
 if %ERRORLEVEL% NEQ 0 (
     echo.

run_pocket_tts_server_exe.bat

@@ -55,6 +55,12 @@ set "STREAM_ARG=--stream"
 set /p "INPUT_STREAM=Enable Streaming? (Y/N) [Y]: "
 if /i "%INPUT_STREAM%"=="N" set "STREAM_ARG="
 
+:: 6. Text Preprocessing Default
+:: Defaults to ON. Only unsets if the user types 'N'.
+set "TEXT_PREPROCESS_ARG=--text-preprocess"
+set /p "INPUT_PREPROCESS=Enable Text Preprocessing? (Y/N) [Y]: "
+if /i "%INPUT_PREPROCESS%"=="N" set "TEXT_PREPROCESS_ARG="
+
 echo.
 echo ========================================================
 echo Starting Pocket TTS Server (EXE)...
@@ -63,12 +69,13 @@ echo Port: %PORT%
 if defined MODEL_PATH echo Model: %MODEL_PATH%
 if defined VOICES_DIR (echo Voices: %VOICES_DIR%) else (echo Voices: Default/None)
 if defined STREAM_ARG (echo Streaming: Enabled) else (echo Streaming: Disabled)
+if defined TEXT_PREPROCESS_ARG (echo Text Preprocessing: Enabled) else (echo Text Preprocessing: Disabled)
 echo ========================================================
 echo.
 
-:: 6. Run Command
+:: 7. Run Command
 if exist "%~dp0PocketTTS-Server.exe" (
-    "%~dp0PocketTTS-Server.exe" --host %HOST% --port %PORT% %MODEL_PATH% %VOICES_DIR% %STREAM_ARG%
+    "%~dp0PocketTTS-Server.exe" --host %HOST% --port %PORT% %MODEL_PATH% %VOICES_DIR% %STREAM_ARG% %TEXT_PREPROCESS_ARG%
 ) else (
     echo [ERROR] PocketTTS-Server.exe not found in the current directory.
     echo Please make sure the executable is located in: %~dp0

server.py

@@ -43,6 +43,7 @@ Environment Variables:
     POCKET_TTS_MODEL_PATH   Path to model file
     POCKET_TTS_VOICES_DIR   Path to voices directory
     POCKET_TTS_STREAM_DEFAULT Enable streaming by default
+    POCKET_TTS_TEXT_PREPROCESS_DEFAULT Enable text preprocessing by default
     POCKET_TTS_LOG_DIR      Log directory path
         """,
     )
@@ -73,6 +74,12 @@ Environment Variables:
         default=Config.STREAM_DEFAULT,
         help='Enable streaming by default for all requests',
     )
+    parser.add_argument(
+        '--text-preprocess',
+        action='store_true',
+        default=Config.TEXT_PREPROCESS_DEFAULT,
+        help='Enable text preprocessing for all requests',
+    )
     parser.add_argument(
         '--log-level',
         type=str,
@@ -93,7 +100,9 @@ def main():
     os.environ.setdefault('POCKET_TTS_LOG_LEVEL', args.log_level)
 
     # Create app
-    app = create_app({'STREAM_DEFAULT': args.stream})
+    app = create_app(
+        {'STREAM_DEFAULT': args.stream, 'TEXT_PREPROCESS_DEFAULT': args.text_preprocess}
+    )
 
     logger = get_logger()