0
# Audio and Text Captchas
1

2
Methods for solving non-visual captcha challenges including audio captchas and text-based questions that require human reasoning or reading comprehension.
3

4
## Capabilities
5

6
### Audio Captcha
7

8
Solves audio captchas where users must transcribe spoken words or numbers from audio files.
9

10
```python { .api }
11
def audio(self, file, lang, **kwargs):
12
    """
13
    Solve audio captcha challenges.
14
    
15
    Parameters:
16
    - file (str): Path to MP3 audio file, URL to MP3 file, or base64-encoded MP3 data (required, max 1MB)
17
    - lang (str): Audio language code - must be one of: "en", "ru", "de", "el", "pt", "fr" (required)
18
    - softId (int): Software developer ID
19
    - callback (str): Pingback URL for result notification
20
    
21
    Returns:
22
    dict: {'captchaId': str, 'code': str} - code contains transcribed text
23
    
24
    Raises:
25
    ValidationException: If file is None, invalid format, or unsupported language
26
    """
27
```
28

29
### Text Captcha
30

31
Solves text-based captcha questions that require human reasoning, reading comprehension, or knowledge.
32

33
```python { .api }
34
def text(self, text, **kwargs):
35
    """
36
    Solve text-based captcha questions.
37
    
38
    Parameters:
39
    - text (str): The question or instruction text (required, max 140 characters, UTF-8)
40
    - lang (str): Language code for the question (optional, see 2captcha.com language list)
41
    - softId (int): Software developer ID
42
    - callback (str): Pingback URL for result notification
43
    
44
    Returns:
45
    dict: {'captchaId': str, 'code': str} - code contains the answer
46
    """
47
```
48

49
## Usage Examples
50

51
### Audio Captcha from File
52

53
```python
54
from twocaptcha import TwoCaptcha, ValidationException
55

56
solver = TwoCaptcha('your_api_key')
57

58
# Solve audio captcha from local file
59
try:
60
    result = solver.audio(
61
        file='path/to/audio_captcha.mp3',
62
        lang='en'
63
    )
64
    print(f"Audio transcription: {result['code']}")
65
except ValidationException as e:
66
    print(f"File error: {e}")
67

68
# Solve with different languages
69
languages = ['en', 'ru', 'de', 'fr', 'pt', 'el']
70
for lang in languages:
71
    try:
72
        result = solver.audio(f'audio_{lang}.mp3', lang)
73
        print(f"{lang.upper()}: {result['code']}")
74
    except Exception as e:
75
        print(f"Error with {lang}: {e}")
76
```
77

78
### Audio Captcha from URL
79

80
```python
81
from twocaptcha import TwoCaptcha
82

83
solver = TwoCaptcha('your_api_key')
84

85
# Solve audio captcha from URL
86
result = solver.audio(
87
    file='https://example.com/audio_captcha.mp3',
88
    lang='en'
89
)
90
print(f"URL audio solved: {result['code']}")
91

92
# Handle download errors
93
try:
94
    result = solver.audio(
95
        file='https://invalid-url.com/missing.mp3',
96
        lang='en'
97
    )
98
except ValidationException as e:
99
    print(f"Download failed: {e}")
100
```
101

102
### Audio Captcha from Base64
103

104
```python
105
from twocaptcha import TwoCaptcha
106
import base64
107

108
solver = TwoCaptcha('your_api_key')
109

110
# Read and encode audio file
111
with open('audio_captcha.mp3', 'rb') as audio_file:
112
    audio_data = audio_file.read()
113
    audio_base64 = base64.b64encode(audio_data).decode('utf-8')
114

115
# Solve from base64 data
116
result = solver.audio(
117
    file=audio_base64,
118
    lang='en'
119
)
120
print(f"Base64 audio solved: {result['code']}")
121
```
122

123
### Text Captcha Questions
124

125
```python
126
from twocaptcha import TwoCaptcha
127

128
solver = TwoCaptcha('your_api_key')
129

130
# Simple math question
131
result = solver.text('What is 2 + 2?')
132
print(f"Math answer: {result['code']}")
133

134
# Reading comprehension
135
result = solver.text(
136
    text='If it is raining, I will stay home. It is raining. Will I go out?',
137
    lang='en'
138
)
139
print(f"Logic answer: {result['code']}")
140

141
# Color/visual description
142
result = solver.text('What color do you get when you mix red and blue?')
143
print(f"Color answer: {result['code']}")
144

145
# Common knowledge
146
result = solver.text('What is the capital of France?')
147
print(f"Geography answer: {result['code']}")
148
```
149

150
### Multilingual Text Captchas
151

152
```python
153
from twocaptcha import TwoCaptcha
154

155
solver = TwoCaptcha('your_api_key')
156

157
# Russian text captcha
158
result = solver.text(
159
    text='Сколько будет 5 + 3?',
160
    lang='ru'
161
)
162
print(f"Russian math: {result['code']}")
163

164
# German text captcha
165
result = solver.text(
166
    text='Wie viele Tage hat eine Woche?',
167
    lang='de'
168
)
169
print(f"German question: {result['code']}")
170

171
# French text captcha  
172
result = solver.text(
173
    text='Combien font 10 - 4?',
174
    lang='fr'
175
)
176
print(f"French math: {result['code']}")
177
```
178

179
### Audio Processing with Error Handling
180

181
```python
182
from twocaptcha import TwoCaptcha, ValidationException
183
import os
184

185
solver = TwoCaptcha('your_api_key')
186

187
def solve_audio_with_validation(file_path, language):
188
    """Solve audio captcha with comprehensive error handling"""
189
    
190
    # Validate file exists
191
    if not os.path.exists(file_path):
192
        raise FileNotFoundError(f"Audio file not found: {file_path}")
193
    
194
    # Validate file size (2captcha has 1MB limit)
195
    file_size = os.path.getsize(file_path)
196
    if file_size > 1024 * 1024:  # 1MB
197
        raise ValueError(f"File too large: {file_size} bytes (max 1MB)")
198
    
199
    # Validate language
200
    supported_langs = ['en', 'ru', 'de', 'el', 'pt', 'fr']
201
    if language not in supported_langs:
202
        raise ValueError(f"Unsupported language: {language}. Use: {supported_langs}")
203
    
204
    try:
205
        result = solver.audio(file_path, language)
206
        return result['code']
207
    except ValidationException as e:
208
        if 'not .mp3' in str(e):
209
            raise ValueError("File must be in MP3 format")
210
        elif 'File could not be downloaded' in str(e):
211
            raise ValueError("Could not access the audio file")
212
        else:
213
            raise
214

215
# Usage with validation
216
try:
217
    transcription = solve_audio_with_validation('audio.mp3', 'en')
218
    print(f"Transcription: {transcription}")
219
except (FileNotFoundError, ValueError, ValidationException) as e:
220
    print(f"Error: {e}")
221
```
222

223
### Text Captcha with Length Validation
224

225
```python
226
from twocaptcha import TwoCaptcha
227

228
solver = TwoCaptcha('your_api_key')
229

230
def solve_text_captcha(question, lang='en'):
231
    """Solve text captcha with input validation"""
232
    
233
    # Validate text length (140 char limit)
234
    if len(question) > 140:
235
        raise ValueError(f"Question too long: {len(question)} chars (max 140)")
236
    
237
    # Validate UTF-8 encoding
238
    try:
239
        question.encode('utf-8')
240
    except UnicodeEncodeError:
241
        raise ValueError("Question contains invalid UTF-8 characters")
242
    
243
    result = solver.text(text=question, lang=lang)
244
    return result['code']
245

246
# Test with various questions
247
questions = [
248
    "What is 7 * 8?",
249
    "Name a fruit that is red",
250
    "How many legs does a spider have?",
251
    "What comes after Wednesday?",
252
    "What is the opposite of hot?"
253
]
254

255
for question in questions:
256
    try:
257
        answer = solve_text_captcha(question)
258
        print(f"Q: {question}")
259
        print(f"A: {answer}\n")
260
    except Exception as e:
261
        print(f"Error with '{question}': {e}\n")
262
```
263

264
### Integration with Web Scraping
265

266
```python
267
from twocaptcha import TwoCaptcha
268
from selenium import webdriver
269
from selenium.webdriver.common.by import By
270
import requests
271
import os
272

273
solver = TwoCaptcha('your_api_key')
274

275
def handle_audio_captcha_on_page():
276
    """Handle audio captcha during web scraping"""
277
    
278
    driver = webdriver.Chrome()
279
    
280
    try:
281
        driver.get('https://site-with-audio-captcha.com/form')
282
        
283
        # Find audio captcha element
284
        audio_element = driver.find_element(By.CSS_SELECTOR, 'audio source')
285
        audio_url = audio_element.get_attribute('src')
286
        
287
        # Download audio file
288
        response = requests.get(audio_url)
289
        audio_path = 'temp_audio.mp3'
290
        
291
        with open(audio_path, 'wb') as f:
292
            f.write(response.content)
293
        
294
        # Solve audio captcha
295
        result = solver.audio(audio_path, 'en')
296
        
297
        # Enter solution
298
        audio_input = driver.find_element(By.NAME, 'audio_response')
299
        audio_input.send_keys(result['code'])
300
        
301
        # Submit form
302
        submit_btn = driver.find_element(By.CSS_SELECTOR, 'input[type="submit"]')
303
        submit_btn.click()
304
        
305
        print(f"Audio captcha solved: {result['code']}")
306
        
307
    finally:
308
        # Cleanup
309
        if os.path.exists('temp_audio.mp3'):
310
            os.remove('temp_audio.mp3')
311
        driver.quit()
312

313
# Usage
314
handle_audio_captcha_on_page()
315
```
316

317
### Batch Processing Audio Captchas
318

319
```python
320
from twocaptcha import TwoCaptcha
321
import os
322
import concurrent.futures
323

324
solver = TwoCaptcha('your_api_key')
325

326
def solve_single_audio(file_path, lang):
327
    """Solve single audio captcha"""
328
    try:
329
        result = solver.audio(file_path, lang)
330
        return (file_path, result['code'], None)
331
    except Exception as e:
332
        return (file_path, None, str(e))
333

334
def batch_solve_audio_captchas(audio_directory, language='en', max_workers=3):
335
    """Solve multiple audio captchas concurrently"""
336
    
337
    # Get all MP3 files
338
    audio_files = [
339
        os.path.join(audio_directory, f) 
340
        for f in os.listdir(audio_directory) 
341
        if f.endswith('.mp3')
342
    ]
343
    
344
    results = []
345
    
346
    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
347
        # Submit all tasks
348
        futures = [
349
            executor.submit(solve_single_audio, file_path, language)
350
            for file_path in audio_files
351
        ]
352
        
353
        # Collect results
354
        for future in concurrent.futures.as_completed(futures):
355
            file_path, transcription, error = future.result()
356
            results.append({
357
                'file': os.path.basename(file_path),
358
                'transcription': transcription,
359
                'error': error
360
            })
361
    
362
    return results
363

364
# Usage
365
results = batch_solve_audio_captchas('./audio_captchas/', 'en')
366

367
for result in results:
368
    if result['error']:
369
        print(f"Error with {result['file']}: {result['error']}")
370
    else:
371
        print(f"{result['file']}: {result['transcription']}")
372
```