Coverage for src/audioio/audiometadata.py: 99%

1"""Working with metadata. 

2 

3To interface the various ways metadata are stored in audio files, the 

4`audioio` package uses nested dictionaries. The keys are always 

5strings. Values are strings, integers, floats, datetimes, or other 

6types. Value strings can also be numbers followed by a unit, 

7e.g. "4.2mV". For defining subsections of key-value pairs, values can 

8be dictionaries. The dictionaries can be nested to arbitrary depth. 

9 

10```py 

11>>> from audioio import print_metadata 

12>>> md = dict(Recording=dict(Experimenter='John Doe', 

13 DateTimeOriginal='2023-10-01T14:10:02', 

14 Count=42), 

15 Hardware=dict(Amplifier='Teensy_Amp 4.1', 

16 Highpass='10Hz', 

17 Gain='120mV')) 

18>>> print_metadata(md) 

19``` 

20results in 

21```txt 

22Recording: 

23 Experimenter : John Doe 

24 DateTimeOriginal: 2023-10-01T14:10:02 

25 Count : 42 

26Hardware: 

27 Amplifier: Teensy_Amp 4.1 

28 Highpass : 10Hz 

29 Gain : 120mV 

30``` 

31 

32Often, audio files have very specific ways to store metadata. You can 

33enforce using these by putting them into a dictionary that is added to 

34the metadata with a key having the name of the metadata type you want, 

35e.g. the "INFO", "BEXT", "iXML", and "GUAN" chunks of RIFF/WAVE files. 

36 

37## Functions 

38 

39The `audiometadata` module provides functions for handling and 

40manipulating these nested dictionaries. Many functions take keys as 

41arguments for finding or setting specific key-value pairs. These keys 

42can be the key of a specific item of a (sub-) dictionary, no matter on 

43which level of the metadata hierarchy it is. For example, simply 

44searching for "Highpass" retrieves the corrseponding value "10Hz", 

45although "Highpass" is contained in the sub-dictionary (or "section") 

46with key "Hardware". The same item can also be specified together with 

47its parent keys: "Hardware.Highpass". Parent keys (or section keys) 

48are by default separated by '.', but all functions have a `sep` 

49key-word that specifies the string separating section names in 

50keys. Key matching is case insensitive. 

51 

52Since the same items are named by many different keys in the different 

53types of metadata data models, the functions also take lists of keys 

54as arguments. 

55 

56Do not forget that you can easily manipulate the metadata by means of 

57the standard functions of dictionaries. 

58 

59If you need to make a copy of the metadata use `deepcopy`: 

60``` 

61from copy import deepcopy 

62md_orig = deepcopy(md) 

63``` 

64 

65### Output 

66 

67Write nested dictionaries as texts: 

68 

69- `write_metadata_text()`: write meta data into a text/yaml file. 

70- `print_metadata()`: write meta data to standard output. 

71 

72### Flatten 

73 

74Conversion between nested and flat dictionaries: 

75 

76- `flatten_metadata()`: flatten hierachical metadata to a single dictionary. 

77- `unflatten_metadata()`: unflatten a previously flattened metadata dictionary. 

78 

79### Parse numbers with units 

80 

81- `parse_number()`: parse string with number and unit. 

82- `change_unit()`: scale numerical value to a new unit. 

83 

84### Find and get values 

85 

86Find keys and get their values parsed and converted to various types: 

87 

88- `find_key()`: find dictionary in metadata hierarchy containing the specified key. 

89- `get_number_unit()`: find a key in metadata and return its number and unit. 

90- `get_number()`: find a key in metadata and return its value in a given unit. 

91- `get_int()`: find a key in metadata and return its integer value. 

92- `get_bool()`: find a key in metadata and return its boolean value. 

93- `get_datetime()`: find keys in metadata and return a datetime. 

94- `get_str()`: find a key in metadata and return its string value. 

95 

96### Organize metadata 

97 

98Add and remove metadata: 

99 

100- `strlist_to_dict()`: convert list of key-value-pair strings to dictionary. 

101- `add_sections()`: add sections to metadata dictionary. 

102- `set_metadata()`: set values of existing metadata. 

103- `add_metadata()`: add or modify key-value pairs. 

104- `move_metadata()`: remove a key from metadata and add it to a dictionary. 

105- `remove_metadata()`: remove key-value pairs or sections from metadata. 

106- `cleanup_metadata()`: remove empty sections from metadata. 

107 

108### Special metadata fields 

109 

110Retrieve and set specific metadata: 

111 

112- `get_gain()`: get gain and unit from metadata. 

113- `update_gain()`: update gain setting in metadata. 

114- `set_starttime()`: set all start-of-recording times in metadata. 

115- `update_starttime()`: update start-of-recording times in metadata. 

116- `bext_history_str()`: assemble a string for the BEXT CodingHistory field. 

117- `add_history()`: add a string describing coding history to metadata. 

118- `add_unwrap()`: add unwrap infos to metadata. 

119 

120Lists of standard keys: 

121 

122- `default_starttime_keys`: keys of times of start of the recording. 

123- `default_timeref_keys`: keys of integer time references. 

124- `default_gain_keys`: keys of gain settings. 

125- `default_history_keys`: keys of strings describing coding history. 

126 

127 

128## Command line script 

129 

130The module can be run as a script from the command line to display the 

131metadata and markers contained in an audio file: 

132 

133```sh 

134> audiometadata logger.wav 

135``` 

136prints 

137```text 

138file: 

139 filepath : logger.wav 

140 samplingrate: 96000Hz 

141 channels : 16 

142 frames : 17280000 

143 duration : 180.000s 

144 

145metadata: 

146 INFO: 

147 Bits : 32 

148 Pins : 1-CH2R,1-CH2L,1-CH3R,1-CH3L,2-CH2R,2-CH2L,2-CH3R,2-CH3L,3-CH2R,3-CH2L,3-CH3R,3-CH3L,4-CH2R,4-CH2L,4-CH3R,4-CH3L 

149 Gain : 165.00mV 

150 uCBoard : Teensy 4.1 

151 MACAdress : 04:e9:e5:15:3e:95 

152 DateTimeOriginal: 2023-10-01T14:10:02 

153 Software : TeeGrid R4-senors-logger v1.0 

154``` 

155 

156 

157Alternatively, the script can be run from the module as: 

158``` 

159python -m src.audioio.metadata audiofile.wav 

160``` 

161 

162Running 

163```sh 

164audiometadata --help 

165``` 

166prints 

167```text 

168usage: audiometadata [-h] [--version] [-f] [-m] [-c] [-t] files [files ...] 

169 

170Convert audio file formats. 

171 

172positional arguments: 

173 files audio file 

174 

175options: 

176 -h, --help show this help message and exit 

177 --version show program's version number and exit 

178 -f list file format only 

179 -m list metadata only 

180 -c list cues/markers only 

181 -t list tags of all riff/wave chunks contained in the file 

182 

183version 2.0.0 by Benda-Lab (2020-2024) 

184``` 

185 

186""" 

187 

188import sys 

189import argparse 

190import numpy as np 

191import datetime as dt 

192from .version import __version__, __year__ 

193 

194 

195def write_metadata_text(fh, meta, prefix='', indent=4, replace=None): 

196 """Write meta data into a text/yaml file or stream. 

197 

198 With the default parameters, the output is a valid yaml file. 

199 

200 Parameters 

201 ---------- 

202 fh: filename or stream 

203 If not a stream, the file with name `fh` is opened. 

204 Otherwise `fh` is used as a stream for writing. 

205 meta: nested dict 

206 Key-value pairs of metadata to be written into the file. 

207 prefix: str 

208 This string is written at the beginning of each line. 

209 indent: int 

210 Number of characters used for indentation of sections. 

211 replace: char or None 

212 If specified, replace special characters by this character. 

213 

214 Examples 

215 -------- 

216 ``` 

217 from audioio import write_metadata 

218 md = dict(aaaa=2, bbbb=dict(ccc=3, ddd=4, eee=dict(hh=5))) 

219 write_metadata('info.txt', md) 

220 ``` 

221 """ 

222 

223 def write_dict(df, md, level, smap): 

224 w = 0 

225 for k in md: 

226 if not isinstance(md[k], dict) and w < len(k): 

227 w = len(k) 

228 for k in md: 

229 clevel = level*indent 

230 if isinstance(md[k], dict): 

231 df.write(f'{prefix}{"":>{clevel}}{k}:\n') 

232 write_dict(df, md[k], level+1, smap) 

233 else: 

234 value = md[k] 

235 if isinstance(value, (list, tuple)): 

236 value = ', '.join([f'{v}' for v in value]) 

237 else: 

238 value = f'{value}' 

239 value = value.replace('\r\n', r'\n') 

240 value = value.replace('\n', r'\n') 

241 if len(smap) > 0: 

242 value = value.translate(smap) 

243 df.write(f'{prefix}{"":>{clevel}}{k:<{w}}: {value}\n') 

244 

245 if not meta: 

246 return 

247 if hasattr(fh, 'write'): 

248 own_file = False 

249 else: 

250 own_file = True 

251 fh = open(fh, 'w') 

252 smap = {} 

253 if replace: 

254 smap = str.maketrans('\r\n\t\x00', ''.join([replace]*4)) 

255 write_dict(fh, meta, 0, smap) 

256 if own_file: 

257 fh.close() 

258 

259 

260def print_metadata(meta, prefix='', indent=4, replace=None): 

261 """Write meta data to standard output. 

262 

263 Parameters 

264 ---------- 

265 meta: nested dict 

266 Key-value pairs of metadata to be written into the file. 

267 prefix: str 

268 This string is written at the beginning of each line. 

269 indent: int 

270 Number of characters used for indentation of sections. 

271 replace: char or None 

272 If specified, replace special characters by this character. 

273 

274 Examples 

275 -------- 

276 ``` 

277 >>> from audioio import print_metadata 

278 >>> md = dict(aaaa=2, bbbb=dict(ccc=3, ddd=4, eee=dict(hh=5)), iiii=dict(jjj=6)) 

279 >>> print_metadata(md) 

280 aaaa: 2 

281 bbbb: 

282 ccc: 3 

283 ddd: 4 

284 eee: 

285 hh: 5 

286 iiii: 

287 jjj: 6 

288 ``` 

289 """ 

290 write_metadata_text(sys.stdout, meta, prefix, indent, replace) 

291 

292 

293def flatten_metadata(md, keep_sections=False, sep='.'): 

294 """Flatten hierarchical metadata to a single dictionary. 

295 

296 Parameters 

297 ---------- 

298 md: nested dict 

299 Metadata as returned by `metadata()`. 

300 keep_sections: bool 

301 If `True`, then prefix keys with section names, separated by `sep`. 

302 sep: str 

303 String for separating section names. 

304 

305 Returns 

306 ------- 

307 d: dict 

308 Non-nested dict containing all key-value pairs of `md`. 

309 

310 Examples 

311 -------- 

312 ``` 

313 >>> from audioio import print_metadata, flatten_metadata 

314 >>> md = dict(aaaa=2, bbbb=dict(ccc=3, ddd=4, eee=dict(hh=5)), iiii=dict(jjj=6)) 

315 >>> print_metadata(md) 

316 aaaa: 2 

317 bbbb: 

318 ccc: 3 

319 ddd: 4 

320 eee: 

321 hh: 5 

322 iiii: 

323 jjj: 6 

324  

325 >>> fmd = flatten_metadata(md, keep_sections=True) 

326 >>> print_metadata(fmd) 

327 aaaa : 2 

328 bbbb.ccc : 3 

329 bbbb.ddd : 4 

330 bbbb.eee.hh: 5 

331 iiii.jjj : 6 

332 ``` 

333 """ 

334 def flatten(cd, section): 

335 df = {} 

336 for k in cd: 

337 if isinstance(cd[k], dict): 

338 df.update(flatten(cd[k], section + k + sep)) 

339 else: 

340 if keep_sections: 

341 df[section+k] = cd[k] 

342 else: 

343 df[k] = cd[k] 

344 return df 

345 

346 return flatten(md, '') 

347 

348 

349def unflatten_metadata(md, sep='.'): 

350 """Unflatten a previously flattened metadata dictionary. 

351 

352 Parameters 

353 ---------- 

354 md: dict 

355 Flat dictionary with key-value pairs as obtained from 

356 `flatten_metadata()` with `keep_sections=True`. 

357 sep: str 

358 String that separates section names. 

359 

360 Returns 

361 ------- 

362 d: nested dict 

363 Hierarchical dictionary with sub-dictionaries and key-value pairs. 

364 

365 Examples 

366 -------- 

367 ``` 

368 >>> from audioio import print_metadata, unflatten_metadata 

369 >>> fmd = {'aaaa': 2, 'bbbb.ccc': 3, 'bbbb.ddd': 4, 'bbbb.eee.hh': 5, 'iiii.jjj': 6} 

370 >>> print_metadata(fmd) 

371 aaaa : 2 

372 bbbb.ccc : 3 

373 bbbb.ddd : 4 

374 bbbb.eee.hh: 5 

375 iiii.jjj : 6 

376  

377 >>> md = unflatten_metadata(fmd) 

378 >>> print_metadata(md) 

379 aaaa: 2 

380 bbbb: 

381 ccc: 3 

382 ddd: 4 

383 eee: 

384 hh: 5 

385 iiii: 

386 jjj: 6 

387 ``` 

388 """ 

389 umd = {} # unflattened metadata 

390 cmd = [umd] # current metadata dicts for each level of the hierarchy 

391 csk = [] # current section keys 

392 for k in md: 

393 ks = k.split(sep) 

394 # go up the hierarchy: 

395 for i in range(len(csk) - len(ks)): 

396 csk.pop() 

397 cmd.pop() 

398 for kss in reversed(ks[:len(csk)]): 

399 if kss == csk[-1]: 

400 break 

401 csk.pop() 

402 cmd.pop() 

403 # add new sections: 

404 for kss in ks[len(csk):-1]: 

405 csk.append(kss) 

406 cmd[-1][kss] = {} 

407 cmd.append(cmd[-1][kss]) 

408 # add key-value pair: 

409 cmd[-1][ks[-1]] = md[k] 

410 return umd 

411 

412 

413def parse_number(s): 

414 """Parse string with number and unit. 

415 

416 Parameters 

417 ---------- 

418 s: str, float, or int 

419 String to be parsed. The initial part of the string is 

420 expected to be a number, the part following the number is 

421 interpreted as the unit. If float or int, then return this 

422 as the value with empty unit. 

423 

424 Returns 

425 ------- 

426 v: None, int, or float 

427 Value of the string as float. Without decimal point, an int is returned. 

428 If the string does not contain a number, None is returned. 

429 u: str 

430 Unit that follows the initial number. 

431 n: int 

432 Number of digits behind the decimal point. 

433 

434 Examples 

435 -------- 

436 

437 ``` 

438 >>> from audioio import parse_number 

439 

440 # integer: 

441 >>> parse_number('42') 

442 (42, '', 0) 

443 

444 # integer with unit: 

445 >>> parse_number('42ms') 

446 (42, 'ms', 0) 

447 

448 # float with unit: 

449 >>> parse_number('42.ms') 

450 (42.0, 'ms', 0) 

451 

452 # float with unit: 

453 >>> parse_number('42.3ms') 

454 (42.3, 'ms', 1) 

455 

456 # float with space and unit: 

457 >>> parse_number('423.17 Hz') 

458 (423.17, 'Hz', 2) 

459 ``` 

460 

461 """ 

462 if not isinstance(s, str): 

463 if isinstance(s, int): 

464 return s, '', 0 

465 if isinstance(s, float): 

466 return s, '', 5 

467 else: 

468 return None, '', 0 

469 n = len(s) 

470 ip = n 

471 have_point = False 

472 for i in range(len(s)): 

473 if s[i] == '.': 

474 if have_point: 

475 n = i 

476 break 

477 have_point = True 

478 ip = i + 1 

479 if not s[i] in '0123456789.+-': 

480 n = i 

481 break 

482 if n == 0: 

483 return None, s, 0 

484 v = float(s[:n]) if have_point else int(s[:n]) 

485 u = s[n:].strip() 

486 nd = n - ip if n >= ip else 0 

487 return v, u, nd 

488 

489 

490unit_prefixes = {'Deka': 1e1, 'deka': 1e1, 'Hekto': 1e2, 'hekto': 1e2, 

491 'kilo': 1e3, 'Kilo': 1e3, 'Mega': 1e6, 'mega': 1e6, 

492 'Giga': 1e9, 'giga': 1e9, 'Tera': 1e12, 'tera': 1e12, 

493 'Peta': 1e15, 'peta': 1e15, 'Exa': 1e18, 'exa': 1e18, 

494 'Dezi': 1e-1, 'dezi': 1e-1, 'Zenti': 1e-2, 'centi': 1e-2, 

495 'Milli': 1e-3, 'milli': 1e-3, 'Micro': 1e-6, 'micro': 1e-6, 

496 'Nano': 1e-9, 'nano': 1e-9, 'Piko': 1e-12, 'piko': 1e-12, 

497 'Femto': 1e-15, 'femto': 1e-15, 'Atto': 1e-18, 'atto': 1e-18, 

498 'da': 1e1, 'h': 1e2, 'K': 1e3, 'k': 1e3, 'M': 1e6, 

499 'G': 1e9, 'T': 1e12, 'P': 1e15, 'E': 1e18, 

500 'd': 1e-1, 'c': 1e-2, 'mu': 1e-6, 'u': 1e-6, 'm': 1e-3, 

501 'n': 1e-9, 'p': 1e-12, 'f': 1e-15, 'a': 1e-18} 

502""" SI prefixes for units with corresponding factors. """ 

503 

504 

505def change_unit(val, old_unit, new_unit): 

506 """Scale numerical value to a new unit. 

507 

508 Adapted from https://github.com/relacs/relacs/blob/1facade622a80e9f51dbf8e6f8171ac74c27f100/options/src/parameter.cc#L1647-L1703 

509 

510 Parameters 

511 ---------- 

512 val: float 

513 Value given in `old_unit`. 

514 old_unit: str 

515 Unit of `val`. 

516 new_unit: str 

517 Requested unit of return value. 

518 

519 Returns 

520 ------- 

521 new_val: float 

522 The input value `val` scaled to `new_unit`. 

523 

524 Examples 

525 -------- 

526 

527 ``` 

528 >>> from audioio import change_unit 

529 >>> change_unit(5, 'mm', 'cm') 

530 0.5 

531 

532 >>> change_unit(5, '', 'cm') 

533 5.0 

534 

535 >>> change_unit(5, 'mm', '') 

536 5.0 

537 

538 >>> change_unit(5, 'cm', 'mm') 

539 50.0 

540 

541 >>> change_unit(4, 'kg', 'g') 

542 4000.0 

543 

544 >>> change_unit(12, '%', '') 

545 0.12 

546 

547 >>> change_unit(1.24, '', '%') 

548 124.0 

549 

550 >>> change_unit(2.5, 'min', 's') 

551 150.0 

552 

553 >>> change_unit(3600, 's', 'h') 

554 1.0 

555 

556 ``` 

557 

558 """ 

559 # missing unit? 

560 if not old_unit and not new_unit: 

561 return val 

562 if not old_unit and new_unit != '%': 

563 return val 

564 if not new_unit and old_unit != '%': 

565 return val 

566 

567 # special units that directly translate into factors: 

568 unit_factors = {'%': 0.01, 'hour': 60.0*60.0, 'h': 60.0*60.0, 'min': 60.0} 

569 

570 # parse old unit: 

571 f1 = 1.0 

572 if old_unit in unit_factors: 

573 f1 = unit_factors[old_unit] 

574 else: 

575 for k in unit_prefixes: 

576 if len(old_unit) > len(k) and old_unit[:len(k)] == k: 

577 f1 = unit_prefixes[k]; 

578 

579 # parse new unit: 

580 f2 = 1.0 

581 if new_unit in unit_factors: 

582 f2 = unit_factors[new_unit] 

583 else: 

584 for k in unit_prefixes: 

585 if len(new_unit) > len(k) and new_unit[:len(k)] == k: 

586 f2 = unit_prefixes[k]; 

587 

588 return val*f1/f2 

589 

590 

591def find_key(metadata, key, sep='.'): 

592 """Find dictionary in metadata hierarchy containing the specified key. 

593 

594 Parameters 

595 ---------- 

596 metadata: nested dict 

597 Metadata. 

598 key: str 

599 Key to be searched for (case insensitive). 

600 May contain section names separated by `sep`, i.e. 

601 "aaa.bbb.ccc" searches "ccc" (can be key-value pair or section) 

602 in section "bbb" that needs to be a subsection of section "aaa". 

603 sep: str 

604 String that separates section names in `key`. 

605 

606 Returns 

607 ------- 

608 md: dict 

609 The innermost dictionary matching some sections of the search key. 

610 If `key` is not at all contained in the metadata, 

611 the top-level dictionary is returned. 

612 key: str 

613 The part of the search key that was not found in `md`, or the 

614 the final part of the search key, found in `md`. 

615 

616 Examples 

617 -------- 

618 

619 Independent of whether found or not found, you can assign to the 

620 returned dictionary with the returned key. 

621 

622 ``` 

623 >>> from audioio import print_metadata, find_key 

624 >>> md = dict(aaaa=2, bbbb=dict(ccc=3, ddd=4, eee=dict(ff=5)), gggg=dict(hhh=6)) 

625 >>> print_metadata(md) 

626 aaaa: 2 

627 bbbb: 

628 ccc: 3 

629 ddd: 4 

630 eee: 

631 ff: 5 

632 gggg: 

633 hhh: 6 

634 

635 >>> m, k = find_key(md, 'bbbb.ddd') 

636 >>> m[k] = 10 

637 >>> print_metadata(md) 

638 aaaa: 2 

639 bbbb: 

640 ccc: 3 

641 ddd: 10 

642 ... 

643 

644 >>> m, k = find_key(md, 'hhh') 

645 >>> m[k] = 12 

646 >>> print_metadata(md) 

647 ... 

648 gggg: 

649 hhh: 12 

650 

651 >>> m, k = find_key(md, 'bbbb.eee.xx') 

652 >>> m[k] = 42 

653 >>> print_metadata(md) 

654 ... 

655 eee: 

656 ff: 5 

657 xx: 42 

658 ... 

659 ``` 

660 

661 When searching for sections, the one conaining the searched section 

662 is returned: 

663 ```py 

664 >>> m, k = find_key(md, 'eee') 

665 >>> m[k]['yy'] = 46 

666 >>> print_metadata(md) 

667 ... 

668 eee: 

669 ff: 5 

670 xx: 42 

671 yy: 46 

672 ... 

673 ``` 

674 

675 """ 

676 def find_keys(metadata, keys): 

677 key = keys[0].strip().upper() 

678 for k in metadata: 

679 if k.upper() == key: 

680 if len(keys) == 1: 

681 # found key: 

682 return True, metadata, k 

683 elif isinstance(metadata[k], dict): 

684 # keep searching within the next section: 

685 return find_keys(metadata[k], keys[1:]) 

686 # search in subsections: 

687 for k in metadata: 

688 if isinstance(metadata[k], dict): 

689 found, mm, kk = find_keys(metadata[k], keys) 

690 if found: 

691 return True, mm, kk 

692 # nothing found: 

693 return False, metadata, sep.join(keys) 

694 

695 if metadata is None: 

696 return {}, None 

697 ks = key.strip().split(sep) 

698 found, mm, kk = find_keys(metadata, ks) 

699 return mm, kk 

700 

701 

702def get_number_unit(metadata, keys, sep='.', default=None, 

703 default_unit='', remove=False): 

704 """Find a key in metadata and return its number and unit. 

705 

706 Parameters 

707 ---------- 

708 metadata: nested dict 

709 Metadata. 

710 keys: str or list of str 

711 Keys in the metadata to be searched for (case insensitive). 

712 Value of the first key found is returned. 

713 May contain section names separated by `sep`.  

714 See `audiometadata.find_key()` for details. 

715 sep: str 

716 String that separates section names in `key`. 

717 default: None, int, or float 

718 Returned value if `key` is not found or the value does 

719 not contain a number. 

720 default_unit: str 

721 Returned unit if `key` is not found or the key's value does 

722 not have a unit. 

723 remove: bool 

724 If `True`, remove the found key from `metadata`. 

725 

726 Returns 

727 ------- 

728 v: None, int, or float 

729 Value referenced by `key` as float. 

730 Without decimal point, an int is returned. 

731 If none of the `keys` was found or 

732 the key`s value does not contain a number, 

733 then `default` is returned. 

734 u: str 

735 Corresponding unit. 

736 

737 Examples 

738 -------- 

739 

740 ``` 

741 >>> from audioio import get_number_unit 

742 >>> md = dict(aaaa='42', bbbb='42.3ms') 

743 

744 # integer: 

745 >>> get_number_unit(md, 'aaaa') 

746 (42, '') 

747 

748 # float with unit: 

749 >>> get_number_unit(md, 'bbbb') 

750 (42.3, 'ms') 

751 

752 # two keys: 

753 >>> get_number_unit(md, ['cccc', 'bbbb']) 

754 (42.3, 'ms') 

755 

756 # not found: 

757 >>> get_number_unit(md, 'cccc') 

758 (None, '') 

759 

760 # not found with default value: 

761 >>> get_number_unit(md, 'cccc', default=1.0, default_unit='a.u.') 

762 (1.0, 'a.u.') 

763 ``` 

764 

765 """ 

766 if not metadata: 

767 return default, default_unit 

768 if not isinstance(keys, (list, tuple, np.ndarray)): 

769 keys = (keys,) 

770 value = default 

771 unit = default_unit 

772 for key in keys: 

773 m, k = find_key(metadata, key, sep) 

774 if k in m: 

775 v, u, _ = parse_number(m[k]) 

776 if v is not None: 

777 if not u: 

778 u = default_unit 

779 if remove: 

780 del m[k] 

781 return v, u 

782 elif u and unit == default_unit: 

783 unit = u 

784 return value, unit 

785 

786 

787def get_number(metadata, unit, keys, sep='.', default=None, remove=False): 

788 """Find a key in metadata and return its value in a given unit. 

789 

790 Parameters 

791 ---------- 

792 metadata: nested dict 

793 Metadata. 

794 unit: str 

795 Unit in which to return numerical value referenced by one of the `keys`. 

796 keys: str or list of str 

797 Keys in the metadata to be searched for (case insensitive). 

798 Value of the first key found is returned. 

799 May contain section names separated by `sep`.  

800 See `audiometadata.find_key()` for details. 

801 sep: str 

802 String that separates section names in `key`. 

803 default: None, int, or float 

804 Returned value if `key` is not found or the value does 

805 not contain a number. 

806 remove: bool 

807 If `True`, remove the found key from `metadata`. 

808 

809 Returns 

810 ------- 

811 v: None or float 

812 Value referenced by `key` as float scaled to `unit`. 

813 If none of the `keys` was found or 

814 the key`s value does not contain a number, 

815 then `default` is returned. 

816 

817 Examples 

818 -------- 

819 

820 ``` 

821 >>> from audioio import get_number 

822 >>> md = dict(aaaa='42', bbbb='42.3ms') 

823 

824 # milliseconds to seconds: 

825 >>> get_number(md, 's', 'bbbb') 

826 0.0423 

827 

828 # milliseconds to microseconds: 

829 >>> get_number(md, 'us', 'bbbb') 

830 42300.0 

831 

832 # value without unit is not scaled: 

833 >>> get_number(md, 'Hz', 'aaaa') 

834 42 

835 

836 # two keys: 

837 >>> get_number(md, 's', ['cccc', 'bbbb']) 

838 0.0423 

839 

840 # not found: 

841 >>> get_number(md, 's', 'cccc') 

842 None 

843 

844 # not found with default value: 

845 >>> get_number(md, 's', 'cccc', default=1.0) 

846 1.0 

847 ``` 

848 

849 """ 

850 v, u = get_number_unit(metadata, keys, sep, None, unit, remove) 

851 if v is None: 

852 return default 

853 else: 

854 return change_unit(v, u, unit) 

855 

856 

857def get_int(metadata, keys, sep='.', default=None, remove=False): 

858 """Find a key in metadata and return its integer value. 

859 

860 Parameters 

861 ---------- 

862 metadata: nested dict 

863 Metadata. 

864 keys: str or list of str 

865 Keys in the metadata to be searched for (case insensitive). 

866 Value of the first key found is returned. 

867 May contain section names separated by `sep`.  

868 See `audiometadata.find_key()` for details. 

869 sep: str 

870 String that separates section names in `key`. 

871 default: None or int 

872 Return value if `key` is not found or the value does 

873 not contain an integer. 

874 remove: bool 

875 If `True`, remove the found key from `metadata`. 

876 

877 Returns 

878 ------- 

879 v: None or int 

880 Value referenced by `key` as integer. 

881 If none of the `keys` was found, 

882 the key's value does not contain a number or represents 

883 a floating point value, then `default` is returned. 

884 

885 Examples 

886 -------- 

887 

888 ``` 

889 >>> from audioio import get_int 

890 >>> md = dict(aaaa='42', bbbb='42.3ms') 

891 

892 # integer: 

893 >>> get_int(md, 'aaaa') 

894 42 

895 

896 # two keys: 

897 >>> get_int(md, ['cccc', 'aaaa']) 

898 42 

899 

900 # float: 

901 >>> get_int(md, 'bbbb') 

902 None 

903 

904 # not found: 

905 >>> get_int(md, 'cccc') 

906 None 

907 

908 # not found with default value: 

909 >>> get_int(md, 'cccc', default=0) 

910 0 

911 ``` 

912 

913 """ 

914 if not metadata: 

915 return default 

916 if not isinstance(keys, (list, tuple, np.ndarray)): 

917 keys = (keys,) 

918 for key in keys: 

919 m, k = find_key(metadata, key, sep) 

920 if k in m: 

921 v, _, n = parse_number(m[k]) 

922 if v is not None and n == 0: 

923 if remove: 

924 del m[k] 

925 return int(v) 

926 return default 

927 

928 

929def get_bool(metadata, keys, sep='.', default=None, remove=False): 

930 """Find a key in metadata and return its boolean value. 

931 

932 Parameters 

933 ---------- 

934 metadata: nested dict 

935 Metadata. 

936 keys: str or list of str 

937 Keys in the metadata to be searched for (case insensitive). 

938 Value of the first key found is returned. 

939 May contain section names separated by `sep`.  

940 See `audiometadata.find_key()` for details. 

941 sep: str 

942 String that separates section names in `key`. 

943 default: None or bool 

944 Return value if `key` is not found or the value does 

945 not specify a boolean value. 

946 remove: bool 

947 If `True`, remove the found key from `metadata`. 

948 

949 Returns 

950 ------- 

951 v: None or bool 

952 Value referenced by `key` as boolean. 

953 True if 'true', 'yes' (case insensitive) or any number larger than zero. 

954 False if 'false', 'no' (case insensitive) or any number equal to zero. 

955 If none of the `keys` was found or 

956 the key's value does specify a boolean value, 

957 then `default` is returned. 

958 

959 Examples 

960 -------- 

961 

962 ``` 

963 >>> from audioio import get_bool 

964 >>> md = dict(aaaa='TruE', bbbb='No', cccc=0, dddd=1, eeee=True, ffff='ui') 

965 

966 # case insensitive: 

967 >>> get_bool(md, 'aaaa') 

968 True 

969 

970 >>> get_bool(md, 'bbbb') 

971 False 

972 

973 >>> get_bool(md, 'cccc') 

974 False 

975 

976 >>> get_bool(md, 'dddd') 

977 True 

978 

979 >>> get_bool(md, 'eeee') 

980 True 

981 

982 # not found: 

983 >>> get_bool(md, 'ffff') 

984 None 

985 

986 # two keys (string is preferred over number): 

987 >>> get_bool(md, ['cccc', 'aaaa']) 

988 True 

989 

990 # two keys (take first match): 

991 >>> get_bool(md, ['cccc', 'ffff']) 

992 False 

993 

994 # not found with default value: 

995 >>> get_bool(md, 'ffff', default=False) 

996 False 

997 ``` 

998 

999 """ 

1000 if not metadata: 

1001 return default 

1002 if not isinstance(keys, (list, tuple, np.ndarray)): 

1003 keys = (keys,) 

1004 val = default 

1005 mv = None 

1006 kv = None 

1007 for key in keys: 

1008 m, k = find_key(metadata, key, sep) 

1009 if k in m and not isinstance(m[k], dict): 

1010 vs = m[k] 

1011 v, _, _ = parse_number(vs) 

1012 if v is not None: 

1013 val = abs(v) > 1e-8 

1014 mv = m 

1015 kv = k 

1016 elif isinstance(vs, str): 

1017 if vs.upper() in ['TRUE', 'T', 'YES', 'Y']: 

1018 if remove: 

1019 del m[k] 

1020 return True 

1021 if vs.upper() in ['FALSE', 'F', 'NO', 'N']: 

1022 if remove: 

1023 del m[k] 

1024 return False 

1025 if not mv is None and not kv is None and remove: 

1026 del mv[kv] 

1027 return val 

1028 

1029 

1030default_starttime_keys = [['DateTimeOriginal'], 

1031 ['OriginationDate', 'OriginationTime'], 

1032 ['Location_Time'], 

1033 ['Timestamp']] 

1034"""Default keys of times of start of the recording in metadata. 

1035Used by `get_datetime()` and `update_starttime()` functions. 

1036""" 

1037 

1038def get_datetime(metadata, keys=default_starttime_keys, 

1039 sep='.', default=None, remove=False): 

1040 """Find keys in metadata and return a datetime. 

1041 

1042 Parameters 

1043 ---------- 

1044 metadata: nested dict 

1045 Metadata. 

1046 keys: tuple of str or list of tuple of str 

1047 Datetimes can be stored in metadata as two separate key-value pairs, 

1048 one for the date and one for the time. Or by a single key-value pair 

1049 for a date-time value. This is why the keys need to be specified in 

1050 tuples with one or two keys. 

1051 The value of the first tuple of keys found is returned. 

1052 Keys may contain section names separated by `sep`.  

1053 See `audiometadata.find_key()` for details. 

1054 The default values for the `keys` find the start time of a recording. 

1055 You can modify the default keys via the `default_starttime_keys` list 

1056 of the `audiometadata` module. 

1057 sep: str 

1058 String that separates section names in `key`. 

1059 default: None or str 

1060 Return value if `key` is not found or the value does 

1061 not contain a string. 

1062 remove: bool 

1063 If `True`, remove the found key from `metadata`. 

1064 

1065 Returns 

1066 ------- 

1067 v: None or datetime 

1068 Datetime referenced by `keys`. 

1069 If none of the `keys` was found, then `default` is returned. 

1070 

1071 Examples 

1072 -------- 

1073 

1074 ``` 

1075 >>> from audioio import get_datetime 

1076 >>> import datetime as dt 

1077 >>> md = dict(date='2024-03-02', time='10:42:24', 

1078 datetime='2023-04-15T22:10:00') 

1079 

1080 # separate date and time: 

1081 >>> get_datetime(md, ('date', 'time')) 

1082 datetime.datetime(2024, 3, 2, 10, 42, 24) 

1083 

1084 # single datetime: 

1085 >>> get_datetime(md, ('datetime',)) 

1086 datetime.datetime(2023, 4, 15, 22, 10)