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```txt 

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) 

19Recording: 

20 Experimenter : John Doe 

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

22 Count : 42 

23Hardware: 

24 Amplifier: Teensy_Amp 4.1 

25 Highpass : 10Hz 

26 Gain : 120mV 

27``` 

28 

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

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

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

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

33 

34## Functions 

35 

36The `audiometadata` module provides functions for handling and 

37manipulating these nested dictionaries. Many functions take keys as 

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

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

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

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

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

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

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

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

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

47keys. Key matching is case insensitive. 

48 

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

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

51as arguments. 

52 

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

54the standard functions of dictionaries. 

55 

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

57``` 

58from copy import deepcopy 

59md_orig = deepcopy(md) 

60``` 

61 

62### Output 

63 

64Write nested dictionaries as texts: 

65 

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

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

68 

69### Flatten 

70 

71Conversion between nested and flat dictionaries: 

72 

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

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

75 

76### Parse numbers with units 

77 

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

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

80 

81### Find and get values 

82 

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

84 

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

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

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

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

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

90- `get_datetime()`: find keys in metadata and return a datatime. 

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

92 

93### Organize metadata 

94 

95Add and remove metadata: 

96 

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

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

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

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

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

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

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

104 

105### Special metadata fields 

106 

107Retrieve and set specific metadata: 

108 

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

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

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

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

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

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

115 

116Lists of standard keys: 

117 

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

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

120- `default_gain_keys`: keys of gain settings. 

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

122 

123 

124## Command line script 

125 

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

127metadata and markers contained in an audio file: 

128 

129```sh 

130> audiometadata logger.wav 

131``` 

132prints 

133```text 

134file: 

135 filepath : logger.wav 

136 samplingrate: 96000Hz 

137 channels : 16 

138 frames : 17280000 

139 duration : 180.000s 

140 

141metadata: 

142 INFO: 

143 Bits : 32 

144 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 

145 Gain : 165.00mV 

146 uCBoard : Teensy 4.1 

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

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

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

150``` 

151 

152 

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

154``` 

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

156``` 

157 

158Running 

159```sh 

160audiometadata --help 

161``` 

162prints 

163```text 

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

165 

166Convert audio file formats. 

167 

168positional arguments: 

169 files audio file 

170 

171options: 

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

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

174 -f list file format only 

175 -m list metadata only 

176 -c list cues/markers only 

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

178 

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

180``` 

181 

182""" 

183 

184import sys 

185import argparse 

186import numpy as np 

187import datetime as dt 

188from .version import __version__, __year__ 

189 

190 

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

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

193 

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

195 

196 Parameters 

197 ---------- 

198 fh: filename or stream 

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

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

201 meta: nested dict 

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

203 prefix: str 

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

205 indent: int 

206 Number of characters used for indentation of sections. 

207 replace: char or None 

208 If specified, replace special characters by this character. 

209 

210 Examples 

211 -------- 

212 ``` 

213 from audioio import write_metadata 

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

215 write_metadata('info.txt', md) 

216 ``` 

217 """ 

218 

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

220 w = 0 

221 for k in md: 

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

223 w = len(k) 

224 for k in md: 

225 clevel = level*indent 

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

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

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

229 else: 

230 value = md[k] 

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

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

233 else: 

234 value = f'{value}' 

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

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

237 if len(smap) > 0: 

238 value = value.translate(smap) 

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

240 

241 if not meta: 

242 return 

243 if hasattr(fh, 'write'): 

244 own_file = False 

245 else: 

246 own_file = True 

247 fh = open(fh, 'w') 

248 smap = {} 

249 if replace: 

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

251 write_dict(fh, meta, 0, smap) 

252 if own_file: 

253 fh.close() 

254 

255 

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

257 """Write meta data to standard output. 

258 

259 Parameters 

260 ---------- 

261 meta: nested dict 

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

263 prefix: str 

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

265 indent: int 

266 Number of characters used for indentation of sections. 

267 replace: char or None 

268 If specified, replace special characters by this character. 

269 

270 Examples 

271 -------- 

272 ``` 

273 >>> from audioio import print_metadata 

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

275 >>> print_metadata(md) 

276 aaaa: 2 

277 bbbb: 

278 ccc: 3 

279 ddd: 4 

280 eee: 

281 hh: 5 

282 iiii: 

283 jjj: 6 

284 ``` 

285 """ 

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

287 

288 

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

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

291 

292 Parameters 

293 ---------- 

294 md: nested dict 

295 Metadata as returned by `metadata()`. 

296 keep_sections: bool 

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

298 sep: str 

299 String for separating section names. 

300 

301 Returns 

302 ------- 

303 d: dict 

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

305 

306 Examples 

307 -------- 

308 ``` 

309 >>> from audioio import print_metadata, flatten_metadata 

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

311 >>> print_metadata(md) 

312 aaaa: 2 

313 bbbb: 

314 ccc: 3 

315 ddd: 4 

316 eee: 

317 hh: 5 

318 iiii: 

319 jjj: 6 

320  

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

322 >>> print_metadata(fmd) 

323 aaaa : 2 

324 bbbb.ccc : 3 

325 bbbb.ddd : 4 

326 bbbb.eee.hh: 5 

327 iiii.jjj : 6 

328 ``` 

329 """ 

330 def flatten(cd, section): 

331 df = {} 

332 for k in cd: 

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

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

335 else: 

336 if keep_sections: 

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

338 else: 

339 df[k] = cd[k] 

340 return df 

341 

342 return flatten(md, '') 

343 

344 

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

346 """Unflatten a previously flattened metadata dictionary. 

347 

348 Parameters 

349 ---------- 

350 md: dict 

351 Flat dictionary with key-value pairs as obtained from 

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

353 sep: str 

354 String that separates section names. 

355 

356 Returns 

357 ------- 

358 d: nested dict 

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

360 

361 Examples 

362 -------- 

363 ``` 

364 >>> from audioio import print_metadata, unflatten_metadata 

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

366 >>> print_metadata(fmd) 

367 aaaa : 2 

368 bbbb.ccc : 3 

369 bbbb.ddd : 4 

370 bbbb.eee.hh: 5 

371 iiii.jjj : 6 

372  

373 >>> md = unflatten_metadata(fmd) 

374 >>> print_metadata(md) 

375 aaaa: 2 

376 bbbb: 

377 ccc: 3 

378 ddd: 4 

379 eee: 

380 hh: 5 

381 iiii: 

382 jjj: 6 

383 ``` 

384 """ 

385 umd = {} # unflattened metadata 

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

387 csk = [] # current section keys 

388 for k in md: 

389 ks = k.split(sep) 

390 # go up the hierarchy: 

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

392 csk.pop() 

393 cmd.pop() 

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

395 if kss == csk[-1]: 

396 break 

397 csk.pop() 

398 cmd.pop() 

399 # add new sections: 

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

401 csk.append(kss) 

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

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

404 # add key-value pair: 

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

406 return umd 

407 

408 

409def parse_number(s): 

410 """Parse string with number and unit. 

411 

412 Parameters 

413 ---------- 

414 s: str, float, or int 

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

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

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

418 as the value with empty unit. 

419 

420 Returns 

421 ------- 

422 v: None, int, or float 

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

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

425 u: str 

426 Unit that follows the initial number. 

427 n: int 

428 Number of digits behind the decimal point. 

429 

430 Examples 

431 -------- 

432 

433 ``` 

434 >>> from audioio import parse_number 

435 

436 # integer: 

437 >>> parse_number('42') 

438 (42, '', 0) 

439 

440 # integer with unit: 

441 >>> parse_number('42ms') 

442 (42, 'ms', 0) 

443 

444 # float with unit: 

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

446 (42.0, 'ms', 0) 

447 

448 # float with unit: 

449 >>> parse_number('42.3ms') 

450 (42.3, 'ms', 1) 

451 

452 # float with space and unit: 

453 >>> parse_number('423.17 Hz') 

454 (423.17, 'Hz', 2) 

455 ``` 

456 

457 """ 

458 if not isinstance(s, str): 

459 if isinstance(s, int): 

460 return s, '', 0 

461 if isinstance(s, float): 

462 return s, '', 5 

463 else: 

464 return None, '', 0 

465 n = len(s) 

466 ip = n 

467 have_point = False 

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

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

470 if have_point: 

471 n = i 

472 break 

473 have_point = True 

474 ip = i + 1 

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

476 n = i 

477 break 

478 if n == 0: 

479 return None, s, 0 

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

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

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

483 return v, u, nd 

484 

485 

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

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

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

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

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

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

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

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

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

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

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

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

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

499 

500 

501def change_unit(val, old_unit, new_unit): 

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

503 

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

505 

506 Parameters 

507 ---------- 

508 val: float 

509 Value given in `old_unit`. 

510 old_unit: str 

511 Unit of `val`. 

512 new_unit: str 

513 Requested unit of return value. 

514 

515 Returns 

516 ------- 

517 new_val: float 

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

519 

520 Examples 

521 -------- 

522 

523 ``` 

524 >>> from audioio import change_unit 

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

526 0.5 

527 

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

529 5.0 

530 

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

532 5.0 

533 

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

535 50.0 

536 

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

538 4000.0 

539 

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

541 0.12 

542 

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

544 124.0 

545 

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

547 150.0 

548 

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

550 1.0 

551 

552 ``` 

553 

554 """ 

555 # missing unit? 

556 if not old_unit and not new_unit: 

557 return val 

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

559 return val 

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

561 return val 

562 

563 # special units that directly translate into factors: 

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

565 

566 # parse old unit: 

567 f1 = 1.0 

568 if old_unit in unit_factors: 

569 f1 = unit_factors[old_unit] 

570 else: 

571 for k in unit_prefixes: 

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

573 f1 = unit_prefixes[k]; 

574 

575 # parse new unit: 

576 f2 = 1.0 

577 if new_unit in unit_factors: 

578 f2 = unit_factors[new_unit] 

579 else: 

580 for k in unit_prefixes: 

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

582 f2 = unit_prefixes[k]; 

583 

584 return val*f1/f2 

585 

586 

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

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

589 

590 Parameters 

591 ---------- 

592 metadata: nested dict 

593 Metadata. 

594 key: str 

595 Key to be searched for (case insensitive). 

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

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

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

599 sep: str 

600 String that separates section names in `key`. 

601 

602 Returns 

603 ------- 

604 md: dict 

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

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

607 the top-level dictionary is returned. 

608 key: str 

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

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

611 

612 Examples 

613 -------- 

614 

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

616 returned dictionary with the returned key. 

617 

618 ``` 

619 >>> from audioio import print_metadata, find_key 

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

621 >>> print_metadata(md) 

622 aaaa: 2 

623 bbbb: 

624 ccc: 3 

625 ddd: 4 

626 eee: 

627 ff: 5 

628 gggg: 

629 hhh: 6 

630 

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

632 >>> m[k] = 10 

633 >>> print_metadata(md) 

634 aaaa: 2 

635 bbbb: 

636 ccc: 3 

637 ddd: 10 

638 ... 

639 

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

641 >>> m[k] = 12 

642 >>> print_metadata(md) 

643 ... 

644 gggg: 

645 hhh: 12 

646 

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

648 >>> m[k] = 42 

649 >>> print_metadata(md) 

650 ... 

651 eee: 

652 ff: 5 

653 xx: 42 

654 ... 

655 ``` 

656 

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

658 is returned: 

659 ```py 

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

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

662 >>> print_metadata(md) 

663 ... 

664 eee: 

665 ff: 5 

666 xx: 42 

667 yy: 46 

668 ... 

669 ``` 

670 

671 """ 

672 def find_keys(metadata, keys): 

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

674 for k in metadata: 

675 if k.upper() == key: 

676 if len(keys) == 1: 

677 # found key: 

678 return True, metadata, k 

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

680 # keep searching within the next section: 

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

682 # search in subsections: 

683 for k in metadata: 

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

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

686 if found: 

687 return True, mm, kk 

688 # nothing found: 

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

690 

691 if not metadata: 

692 return {}, None 

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

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

695 return mm, kk 

696 

697 

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

699 default_unit='', remove=False): 

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

701 

702 Parameters 

703 ---------- 

704 metadata: nested dict 

705 Metadata. 

706 keys: str or list of str 

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

708 Value of the first key found is returned. 

709 May contain section names separated by `sep`.  

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

711 sep: str 

712 String that separates section names in `key`. 

713 default: None, int, or float 

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

715 not contain a number. 

716 default_unit: str 

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

718 not have a unit. 

719 remove: bool 

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

721 

722 Returns 

723 ------- 

724 v: None, int, or float 

725 Value referenced by `key` as float. 

726 Without decimal point, an int is returned. 

727 If none of the `keys` was found or 

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

729 then `default` is returned. 

730 u: str 

731 Corresponding unit. 

732 

733 Examples 

734 -------- 

735 

736 ``` 

737 >>> from audioio import get_number_unit 

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

739 

740 # integer: 

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

742 (42, '') 

743 

744 # float with unit: 

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

746 (42.3, 'ms') 

747 

748 # two keys: 

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

750 (42.3, 'ms') 

751 

752 # not found: 

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

754 (None, '') 

755 

756 # not found with default value: 

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

758 (1.0, 'a.u.') 

759 ``` 

760 

761 """ 

762 if not metadata: 

763 return default, default_unit 

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

765 keys = (keys,) 

766 value = default 

767 unit = default_unit 

768 for key in keys: 

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

770 if k in m: 

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

772 if v is not None: 

773 if not u: 

774 u = default_unit 

775 if remove: 

776 del m[k] 

777 return v, u 

778 elif u and unit == default_unit: 

779 unit = u 

780 return value, unit 

781 

782 

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

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

785 

786 Parameters 

787 ---------- 

788 metadata: nested dict 

789 Metadata. 

790 unit: str 

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

792 keys: str or list of str 

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

794 Value of the first key found is returned. 

795 May contain section names separated by `sep`.  

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

797 sep: str 

798 String that separates section names in `key`. 

799 default: None, int, or float 

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

801 not contain a number. 

802 remove: bool 

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

804 

805 Returns 

806 ------- 

807 v: None or float 

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

809 If none of the `keys` was found or 

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

811 then `default` is returned. 

812 

813 Examples 

814 -------- 

815 

816 ``` 

817 >>> from audioio import get_number 

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

819 

820 # milliseconds to seconds: 

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

822 0.0423 

823 

824 # milliseconds to microseconds: 

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

826 42300.0 

827 

828 # value without unit is not scaled: 

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

830 42 

831 

832 # two keys: 

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

834 0.0423 

835 

836 # not found: 

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

838 None 

839 

840 # not found with default value: 

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

842 1.0 

843 ``` 

844 

845 """ 

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

847 if v is None: 

848 return default 

849 else: 

850 return change_unit(v, u, unit) 

851 

852 

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

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

855 

856 Parameters 

857 ---------- 

858 metadata: nested dict 

859 Metadata. 

860 keys: str or list of str 

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

862 Value of the first key found is returned. 

863 May contain section names separated by `sep`.  

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

865 sep: str 

866 String that separates section names in `key`. 

867 default: None or int 

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

869 not contain an integer. 

870 remove: bool 

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

872 

873 Returns 

874 ------- 

875 v: None or int 

876 Value referenced by `key` as integer. 

877 If none of the `keys` was found, 

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

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

880 

881 Examples 

882 -------- 

883 

884 ``` 

885 >>> from audioio import get_int 

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

887 

888 # integer: 

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

890 42 

891 

892 # two keys: 

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

894 42 

895 

896 # float: 

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

898 None 

899 

900 # not found: 

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

902 None 

903 

904 # not found with default value: 

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

906 0 

907 ``` 

908 

909 """ 

910 if not metadata: 

911 return default 

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

913 keys = (keys,) 

914 for key in keys: 

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

916 if k in m: 

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

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

919 if remove: 

920 del m[k] 

921 return int(v) 

922 return default 

923 

924 

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

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

927 

928 Parameters 

929 ---------- 

930 metadata: nested dict 

931 Metadata. 

932 keys: str or list of str 

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

934 Value of the first key found is returned. 

935 May contain section names separated by `sep`.  

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

937 sep: str 

938 String that separates section names in `key`. 

939 default: None or bool 

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

941 not specify a boolean value. 

942 remove: bool 

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

944 

945 Returns 

946 ------- 

947 v: None or bool 

948 Value referenced by `key` as boolean. 

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

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

951 If none of the `keys` was found or 

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

953 then `default` is returned. 

954 

955 Examples 

956 -------- 

957 

958 ``` 

959 >>> from audioio import get_bool 

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

961 

962 # case insensitive: 

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

964 True 

965 

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

967 False 

968 

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

970 False 

971 

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

973 True 

974 

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

976 True 

977 

978 # not found: 

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

980 None 

981 

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

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

984 True 

985 

986 # two keys (take first match): 

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

988 False 

989 

990 # not found with default value: 

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

992 False 

993 ``` 

994 

995 """ 

996 if not metadata: 

997 return default 

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

999 keys = (keys,) 

1000 val = default 

1001 mv = None 

1002 kv = None 

1003 for key in keys: 

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

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

1006 vs = m[k] 

1007 v, _, _ = parse_number(vs) 

1008 if v is not None: 

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

1010 mv = m 

1011 kv = k 

1012 elif isinstance(vs, str): 

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

1014 if remove: 

1015 del m[k] 

1016 return True 

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

1018 if remove: 

1019 del m[k] 

1020 return False 

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

1022 del mv[kv] 

1023 return val 

1024 

1025 

1026default_starttime_keys = [['DateTimeOriginal'], 

1027 ['OriginationDate', 'OriginationTime'], 

1028 ['Location_Time'], 

1029 ['Timestamp']] 

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

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

1032""" 

1033 

1034def get_datetime(metadata, keys=default_starttime_keys, 

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

1036 """Find keys in metadata and return a datatime. 

1037 

1038 Parameters 

1039 ---------- 

1040 metadata: nested dict 

1041 Metadata. 

1042 keys: tuple of str or list of tuple of str 

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

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

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

1046 tuples with one or tow keys. 

1047 Value of the first tuple of keys found is returned. 

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

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

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

1051 of the `audiometadata` module. 

1052 sep: str 

1053 String that separates section names in `key`. 

1054 default: None or str 

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

1056 not contain a string. 

1057 remove: bool 

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

1059 

1060 Returns 

1061 ------- 

1062 v: None or datetime 

1063 Datetime referenced by `keys`. 

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

1065 

1066 Examples 

1067 -------- 

1068 

1069 ``` 

1070 >>> from audioio import get_datetime 

1071 >>> import datetime as dt 

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

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

1074 

1075 # separate date and time: 

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

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

1078 

1079 # single datetime: 

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

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

1082 

1083 # two alternative key tuples: 

1084 >>> get_datetime(md, [('aaaa',), ('date', 'time')]) 

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

1086 

1087 # not found: