VirtualBox

source: vbox/trunk/src/VBox/Main/src-client/DrvAudioVideoRec.cpp@ 70772

Last change on this file since 70772 was 70644, checked in by vboxsync, 6 years ago

Audio/Main: More code needed for attaching / detaching host backends at runtime.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 37.1 KB
Line 
1/* $Id: DrvAudioVideoRec.cpp 70644 2018-01-19 12:20:33Z vboxsync $ */
2/** @file
3 * Video recording audio backend for Main.
4 */
5
6/*
7 * Copyright (C) 2016-2017 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 */
17
18/* This code makes use of the Opus codec (libopus):
19 *
20 * Copyright 2001-2011 Xiph.Org, Skype Limited, Octasic,
21 * Jean-Marc Valin, Timothy B. Terriberry,
22 * CSIRO, Gregory Maxwell, Mark Borgerding,
23 * Erik de Castro Lopo
24 *
25 * Redistribution and use in source and binary forms, with or without
26 * modification, are permitted provided that the following conditions
27 * are met:
28 *
29 * - Redistributions of source code must retain the above copyright
30 * notice, this list of conditions and the following disclaimer.
31 *
32 * - Redistributions in binary form must reproduce the above copyright
33 * notice, this list of conditions and the following disclaimer in the
34 * documentation and/or other materials provided with the distribution.
35 *
36 * - Neither the name of Internet Society, IETF or IETF Trust, nor the
37 * names of specific contributors, may be used to endorse or promote
38 * products derived from this software without specific prior written
39 * permission.
40 *
41 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
42 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
43 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
44 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
45 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
46 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
47 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
48 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
49 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
50 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
51 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
52 *
53 * Opus is subject to the royalty-free patent licenses which are
54 * specified at:
55 *
56 * Xiph.Org Foundation:
57 * https://datatracker.ietf.org/ipr/1524/
58 *
59 * Microsoft Corporation:
60 * https://datatracker.ietf.org/ipr/1914/
61 *
62 * Broadcom Corporation:
63 * https://datatracker.ietf.org/ipr/1526/
64 *
65 */
66
67/**
68 * This driver is part of Main and is responsible for providing audio
69 * data to Main's video capturing feature.
70 *
71 * The driver itself implements a PDM host audio backend, which in turn
72 * provides the driver with the required audio data and audio events.
73 *
74 * For now there is support for the following destinations (called "sinks"):
75 *
76 * - Direct writing of .webm files to the host.
77 * - Communicating with Main via the Console object to send the encoded audio data to.
78 * The Console object in turn then will route the data to the Display / video capturing interface then.
79 */
80
81
82/*********************************************************************************************************************************
83* Header Files *
84*********************************************************************************************************************************/
85#define LOG_GROUP LOG_GROUP_DRV_HOST_AUDIO
86#include "LoggingNew.h"
87
88#include "DrvAudioVideoRec.h"
89#include "ConsoleImpl.h"
90
91#include "../../Devices/Audio/DrvAudio.h"
92#include "WebMWriter.h"
93
94#include <iprt/mem.h>
95#include <iprt/cdefs.h>
96
97#include <VBox/vmm/pdmaudioifs.h>
98#include <VBox/vmm/pdmdrv.h>
99#include <VBox/vmm/cfgm.h>
100#include <VBox/err.h>
101
102#ifdef VBOX_WITH_LIBOPUS
103# include <opus.h>
104#endif
105
106
107/*********************************************************************************************************************************
108* Defines *
109*********************************************************************************************************************************/
110
111#define AVREC_OPUS_HZ_MAX 48000 /** Maximum sample rate (in Hz) Opus can handle. */
112
113
114/*********************************************************************************************************************************
115* Structures and Typedefs *
116*********************************************************************************************************************************/
117
118/**
119 * Enumeration for specifying the recording container type.
120 */
121typedef enum AVRECCONTAINERTYPE
122{
123 /** Unknown / invalid container type. */
124 AVRECCONTAINERTYPE_UNKNOWN = 0,
125 /** Recorded data goes to Main / Console. */
126 AVRECCONTAINERTYPE_MAIN_CONSOLE = 1,
127 /** Recorded data will be written to a .webm file. */
128 AVRECCONTAINERTYPE_WEBM = 2
129} AVRECCONTAINERTYPE;
130
131/**
132 * Structure for keeping generic container parameters.
133 */
134typedef struct AVRECCONTAINERPARMS
135{
136 /** The container's type. */
137 AVRECCONTAINERTYPE enmType;
138
139} AVRECCONTAINERPARMS, *PAVRECCONTAINERPARMS;
140
141/**
142 * Structure for keeping container-specific data.
143 */
144typedef struct AVRECCONTAINER
145{
146 /** Generic container parameters. */
147 AVRECCONTAINERPARMS Parms;
148
149 union
150 {
151 struct
152 {
153 /** Pointer to Console. */
154 Console *pConsole;
155 } Main;
156
157 struct
158 {
159 /** Pointer to WebM container to write recorded audio data to.
160 * See the AVRECMODE enumeration for more information. */
161 WebMWriter *pWebM;
162 /** Assigned track number from WebM container. */
163 uint8_t uTrack;
164 } WebM;
165 };
166} AVRECCONTAINER, *PAVRECCONTAINER;
167
168/**
169 * Structure for keeping generic codec parameters.
170 */
171typedef struct AVRECCODECPARMS
172{
173 /** The encoding rate to use. */
174 uint32_t uHz;
175 /** Number of audio channels to encode.
176 * Currently we only supported stereo (2) channels. */
177 uint8_t cChannels;
178 /** Bits per sample. */
179 uint8_t cBits;
180 /** The codec's bitrate. 0 if not used / cannot be specified. */
181 uint32_t uBitrate;
182
183} AVRECCODECPARMS, *PAVRECCODECPARMS;
184
185/**
186 * Structure for keeping codec-specific data.
187 */
188typedef struct AVRECCODEC
189{
190 /** Generic codec parameters. */
191 AVRECCODECPARMS Parms;
192 union
193 {
194#ifdef VBOX_WITH_LIBOPUS
195 struct
196 {
197 /** Encoder we're going to use. */
198 OpusEncoder *pEnc;
199 /** Time (in ms) an (encoded) frame takes.
200 *
201 * For Opus, valid frame sizes are:
202 * ms Frame size
203 * 2.5 120
204 * 5 240
205 * 10 480
206 * 20 (Default) 960
207 * 40 1920
208 * 60 2880
209 */
210 uint32_t msFrame;
211 } Opus;
212#endif /* VBOX_WITH_LIBOPUS */
213 };
214
215#ifdef VBOX_WITH_STATISTICS /** @todo Make these real STAM values. */
216 struct
217 {
218 /** Number of frames encoded. */
219 uint64_t cEncFrames;
220 /** Total time (in ms) of already encoded audio data. */
221 uint64_t msEncTotal;
222 } STAM;
223#endif /* VBOX_WITH_STATISTICS */
224
225} AVRECCODEC, *PAVRECCODEC;
226
227typedef struct AVRECSINK
228{
229 /** @todo Add types for container / codec as soon as we implement more stuff. */
230
231 /** Container data to use for data processing. */
232 AVRECCONTAINER Con;
233 /** Codec data this sink uses for encoding. */
234 AVRECCODEC Codec;
235 /** Timestamp (in ms) of when the sink was created. */
236 uint64_t tsStartMs;
237} AVRECSINK, *PAVRECSINK;
238
239/**
240 * Audio video recording (output) stream.
241 */
242typedef struct AVRECSTREAM
243{
244 /** The stream's acquired configuration. */
245 PPDMAUDIOSTREAMCFG pCfg;
246 /** (Audio) frame buffer. */
247 PRTCIRCBUF pCircBuf;
248 /** Pointer to sink to use for writing. */
249 PAVRECSINK pSink;
250 /** Last encoded PTS (in ms). */
251 uint64_t uLastPTSMs;
252} AVRECSTREAM, *PAVRECSTREAM;
253
254/**
255 * Video recording audio driver instance data.
256 */
257typedef struct DRVAUDIOVIDEOREC
258{
259 /** Pointer to audio video recording object. */
260 AudioVideoRec *pAudioVideoRec;
261 /** Pointer to the driver instance structure. */
262 PPDMDRVINS pDrvIns;
263 /** Pointer to host audio interface. */
264 PDMIHOSTAUDIO IHostAudio;
265 /** Pointer to the console object. */
266 ComObjPtr<Console> pConsole;
267 /** Pointer to the DrvAudio port interface that is above us. */
268 PPDMIAUDIOCONNECTOR pDrvAudio;
269 /** The driver's sink for writing output to. */
270 AVRECSINK Sink;
271} DRVAUDIOVIDEOREC, *PDRVAUDIOVIDEOREC;
272
273/** Makes DRVAUDIOVIDEOREC out of PDMIHOSTAUDIO. */
274#define PDMIHOSTAUDIO_2_DRVAUDIOVIDEOREC(pInterface) \
275 ( (PDRVAUDIOVIDEOREC)((uintptr_t)pInterface - RT_OFFSETOF(DRVAUDIOVIDEOREC, IHostAudio)) )
276
277/**
278 * Initializes a recording sink.
279 *
280 * @returns IPRT status code.
281 * @param pThis Driver instance.
282 * @param pSink Sink to initialize.
283 * @param pConParms Container parameters to set.
284 * @param pCodecParms Codec parameters to set.
285 */
286static int avRecSinkInit(PDRVAUDIOVIDEOREC pThis, PAVRECSINK pSink, PAVRECCONTAINERPARMS pConParms, PAVRECCODECPARMS pCodecParms)
287{
288 uint32_t uHz = pCodecParms->uHz;
289 uint8_t cBits = pCodecParms->cBits;
290 uint8_t cChannels = pCodecParms->cChannels;
291 uint32_t uBitrate = pCodecParms->uBitrate;
292
293 /* Opus only supports certain input sample rates in an efficient manner.
294 * So make sure that we use those by resampling the data to the requested rate. */
295 if (uHz > 24000) uHz = AVREC_OPUS_HZ_MAX;
296 else if (uHz > 16000) uHz = 24000;
297 else if (uHz > 12000) uHz = 16000;
298 else if (uHz > 8000 ) uHz = 12000;
299 else uHz = 8000;
300
301 if (cChannels > 2)
302 {
303 LogRel(("VideoRec: More than 2 (stereo) channels are not supported at the moment\n"));
304 cChannels = 2;
305 }
306
307 LogRel2(("VideoRec: Recording audio in %RU16Hz, %RU8 channels, %RU32 bitrate\n", uHz, cChannels, uBitrate));
308
309 int orc;
310 OpusEncoder *pEnc = opus_encoder_create(uHz, cChannels, OPUS_APPLICATION_AUDIO, &orc);
311 if (orc != OPUS_OK)
312 {
313 LogRel(("VideoRec: Audio codec failed to initialize: %s\n", opus_strerror(orc)));
314 return VERR_AUDIO_BACKEND_INIT_FAILED;
315 }
316
317 AssertPtr(pEnc);
318
319 opus_encoder_ctl(pEnc, OPUS_SET_BITRATE(uBitrate));
320 if (orc != OPUS_OK)
321 {
322 opus_encoder_destroy(pEnc);
323 pEnc = NULL;
324
325 LogRel(("VideoRec: Audio codec failed to set bitrate (%RU32): %s\n", uBitrate, opus_strerror(orc)));
326 return VERR_AUDIO_BACKEND_INIT_FAILED;
327 }
328
329 int rc = VINF_SUCCESS;
330
331 try
332 {
333 switch (pConParms->enmType)
334 {
335 case AVRECCONTAINERTYPE_MAIN_CONSOLE:
336 {
337 if (pThis->pConsole)
338 {
339 pSink->Con.Main.pConsole = pThis->pConsole;
340 }
341 else
342 rc = VERR_NOT_SUPPORTED;
343 break;
344 }
345
346 case AVRECCONTAINERTYPE_WEBM:
347 {
348#ifdef VBOX_AUDIO_DEBUG_DUMP_PCM_DATA
349 /* If we only record audio, create our own WebM writer instance here. */
350 if (!pSink->Con.WebM.pWebM) /* Do we already have our WebM writer instance? */
351 {
352 char szFile[RTPATH_MAX];
353 if (RTStrPrintf(szFile, sizeof(szFile), "%s%s",
354 VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH, "DrvAudioVideoRec.webm"))
355 {
356 /** @todo Add sink name / number to file name. */
357
358 pSink->Con.WebM.pWebM = new WebMWriter();
359 rc = pSink->Con.WebM.pWebM->Create(szFile,
360 /** @todo Add option to add some suffix if file exists instead of overwriting? */
361 RTFILE_O_CREATE_REPLACE | RTFILE_O_WRITE | RTFILE_O_DENY_NONE,
362 WebMWriter::AudioCodec_Opus, WebMWriter::VideoCodec_None);
363 if (RT_SUCCESS(rc))
364 {
365 rc = pSink->Con.WebM.pWebM->AddAudioTrack(uHz, cChannels, cBits,
366 &pSink->Con.WebM.uTrack);
367 if (RT_SUCCESS(rc))
368 {
369 LogRel(("VideoRec: Recording audio to file '%s'\n", szFile));
370 }
371 else
372 LogRel(("VideoRec: Error creating audio track for file '%s' (%Rrc)\n", szFile, rc));
373 }
374 else
375 LogRel(("VideoRec: Error creating audio file '%s' (%Rrc)\n", szFile, rc));
376 }
377 else
378 {
379 AssertFailed(); /* Should never happen. */
380 LogRel(("VideoRec: Error creating audio file path\n"));
381 }
382 }
383#else
384 rc = VERR_NOT_SUPPORTED;
385#endif /* VBOX_AUDIO_DEBUG_DUMP_PCM_DATA */
386 break;
387 }
388
389 default:
390 rc = VERR_NOT_SUPPORTED;
391 break;
392 }
393 }
394 catch (std::bad_alloc)
395 {
396#ifdef VBOX_AUDIO_DEBUG_DUMP_PCM_DATA
397 rc = VERR_NO_MEMORY;
398#endif
399 }
400
401 if (RT_SUCCESS(rc))
402 {
403 pSink->Con.Parms.enmType = pConParms->enmType;
404
405 pSink->Codec.Parms.uHz = uHz;
406 pSink->Codec.Parms.cChannels = cChannels;
407 pSink->Codec.Parms.cBits = cBits;
408 pSink->Codec.Parms.uBitrate = uBitrate;
409
410 pSink->Codec.Opus.pEnc = pEnc;
411 pSink->Codec.Opus.msFrame = 20; /** @todo 20 ms of audio data. Make this configurable? */
412
413#ifdef VBOX_WITH_STATISTICS
414 pSink->Codec.STAM.cEncFrames = 0;
415 pSink->Codec.STAM.msEncTotal = 0;
416#endif
417
418 pSink->tsStartMs = RTTimeMilliTS();
419 }
420 else
421 {
422 if (pEnc)
423 {
424 opus_encoder_destroy(pEnc);
425 pEnc = NULL;
426 }
427
428 LogRel(("VideoRec: Error creating sink (%Rrc)\n", rc));
429 }
430
431 return rc;
432}
433
434
435/**
436 * Shuts down (closes) a recording sink,
437 *
438 * @returns IPRT status code.
439 * @param pSink Recording sink to shut down.
440 */
441static void avRecSinkShutdown(PAVRECSINK pSink)
442{
443 AssertPtrReturnVoid(pSink);
444
445#ifdef VBOX_WITH_LIBOPUS
446 if (pSink->Codec.Opus.pEnc)
447 {
448 opus_encoder_destroy(pSink->Codec.Opus.pEnc);
449 pSink->Codec.Opus.pEnc = NULL;
450 }
451#endif
452 switch (pSink->Con.Parms.enmType)
453 {
454 case AVRECCONTAINERTYPE_WEBM:
455 {
456 if (pSink->Con.WebM.pWebM)
457 {
458 LogRel2(("VideoRec: Finished recording audio to file '%s' (%zu bytes)\n",
459 pSink->Con.WebM.pWebM->GetFileName().c_str(), pSink->Con.WebM.pWebM->GetFileSize()));
460
461 int rc2 = pSink->Con.WebM.pWebM->Close();
462 AssertRC(rc2);
463
464 delete pSink->Con.WebM.pWebM;
465 pSink->Con.WebM.pWebM = NULL;
466 }
467 break;
468 }
469
470 case AVRECCONTAINERTYPE_MAIN_CONSOLE:
471 default:
472 break;
473 }
474}
475
476
477/**
478 * Creates an audio output stream and associates it with the specified recording sink.
479 *
480 * @returns IPRT status code.
481 * @param pThis Driver instance.
482 * @param pStreamAV Audio output stream to create.
483 * @param pSink Recording sink to associate audio output stream to.
484 * @param pCfgReq Requested configuration by the audio backend.
485 * @param pCfgAcq Acquired configuration by the audio output stream.
486 */
487static int avRecCreateStreamOut(PDRVAUDIOVIDEOREC pThis, PAVRECSTREAM pStreamAV,
488 PAVRECSINK pSink, PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq)
489{
490 AssertPtrReturn(pThis, VERR_INVALID_POINTER);
491 AssertPtrReturn(pStreamAV, VERR_INVALID_POINTER);
492 AssertPtrReturn(pSink, VERR_INVALID_POINTER);
493 AssertPtrReturn(pCfgReq, VERR_INVALID_POINTER);
494 AssertPtrReturn(pCfgAcq, VERR_INVALID_POINTER);
495
496 if (pCfgReq->DestSource.Dest != PDMAUDIOPLAYBACKDEST_FRONT)
497 {
498 AssertFailed();
499
500 if (pCfgAcq)
501 pCfgAcq->cFrameBufferHint = 0;
502
503 LogRel2(("VideoRec: Support for surround audio not implemented yet\n"));
504 return VERR_NOT_SUPPORTED;
505 }
506
507 int rc = VINF_SUCCESS;
508
509#ifdef VBOX_WITH_LIBOPUS
510 const unsigned cFrames = 2; /** @todo Use the PreRoll param for that? */
511
512 const uint32_t csFrame = pSink->Codec.Parms.uHz / (1000 /* s in ms */ / pSink->Codec.Opus.msFrame);
513 const uint32_t cbFrame = csFrame * pSink->Codec.Parms.cChannels * (pSink->Codec.Parms.cBits / 8 /* Bytes */);
514
515 rc = RTCircBufCreate(&pStreamAV->pCircBuf, cbFrame * cFrames);
516 if (RT_SUCCESS(rc))
517 {
518 pStreamAV->pSink = pSink; /* Assign sink to stream. */
519 pStreamAV->uLastPTSMs = 0;
520
521 if (pCfgAcq)
522 {
523 /* Make sure to let the driver backend know that we need the audio data in
524 * a specific sampling rate Opus is optimized for. */
525 pCfgAcq->Props.uHz = pSink->Codec.Parms.uHz;
526 pCfgAcq->Props.cShift = PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(pCfgAcq->Props.cBits, pCfgAcq->Props.cChannels);
527 pCfgAcq->cFrameBufferHint = _4K; /** @todo Make this configurable. */
528 }
529 }
530#else
531 RT_NOREF(pThis, pSink, pStreamAV, pCfgReq, pCfgAcq);
532 rc = VERR_NOT_SUPPORTED;
533#endif /* VBOX_WITH_LIBOPUS */
534
535 LogFlowFuncLeaveRC(rc);
536 return rc;
537}
538
539
540/**
541 * Destroys (closes) an audio output stream.
542 *
543 * @returns IPRT status code.
544 * @param pThis Driver instance.
545 * @param pStreamAV Audio output stream to destroy.
546 */
547static int avRecDestroyStreamOut(PDRVAUDIOVIDEOREC pThis, PAVRECSTREAM pStreamAV)
548{
549 RT_NOREF(pThis);
550
551 if (pStreamAV->pCircBuf)
552 {
553 RTCircBufDestroy(pStreamAV->pCircBuf);
554 pStreamAV->pCircBuf = NULL;
555 }
556
557 return VINF_SUCCESS;
558}
559
560
561/**
562 * Controls an audio output stream
563 *
564 * @returns IPRT status code.
565 * @param pThis Driver instance.
566 * @param pStreamAV Audio output stream to control.
567 * @param enmStreamCmd Stream command to issue.
568 */
569static int avRecControlStreamOut(PDRVAUDIOVIDEOREC pThis,
570 PAVRECSTREAM pStreamAV, PDMAUDIOSTREAMCMD enmStreamCmd)
571{
572 RT_NOREF(pThis, pStreamAV);
573
574 switch (enmStreamCmd)
575 {
576 case PDMAUDIOSTREAMCMD_ENABLE:
577 case PDMAUDIOSTREAMCMD_DISABLE:
578 case PDMAUDIOSTREAMCMD_RESUME:
579 case PDMAUDIOSTREAMCMD_PAUSE:
580 break;
581
582 default:
583 AssertMsgFailed(("Invalid command %ld\n", enmStreamCmd));
584 break;
585 }
586
587 return VINF_SUCCESS;
588}
589
590
591/**
592 * @interface_method_impl{PDMIHOSTAUDIO,pfnInit}
593 */
594static DECLCALLBACK(int) drvAudioVideoRecInit(PPDMIHOSTAUDIO pInterface)
595{
596 AssertPtrReturn(pInterface, VERR_INVALID_POINTER);
597
598 LogFlowFuncEnter();
599
600 PDRVAUDIOVIDEOREC pThis = PDMIHOSTAUDIO_2_DRVAUDIOVIDEOREC(pInterface);
601
602 AVRECCONTAINERPARMS ContainerParms;
603 ContainerParms.enmType = AVRECCONTAINERTYPE_MAIN_CONSOLE; /** @todo Make this configurable. */
604
605 AVRECCODECPARMS CodecParms;
606 CodecParms.uHz = AVREC_OPUS_HZ_MAX; /** @todo Make this configurable. */
607 CodecParms.cChannels = 2; /** @todo Make this configurable. */
608 CodecParms.cBits = 16; /** @todo Make this configurable. */
609 CodecParms.uBitrate = 196000; /** @todo Make this configurable. */
610
611 int rc = avRecSinkInit(pThis, &pThis->Sink, &ContainerParms, &CodecParms);
612 if (RT_FAILURE(rc))
613 {
614 LogRel(("VideoRec: Audio recording driver failed to initialize, rc=%Rrc\n", rc));
615 }
616 else
617 LogRel2(("VideoRec: Audio recording driver initialized\n"));
618
619 return rc;
620}
621
622
623/**
624 * @interface_method_impl{PDMIHOSTAUDIO,pfnStreamCapture}
625 */
626static DECLCALLBACK(int) drvAudioVideoRecStreamCapture(PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
627 void *pvBuf, uint32_t cxBuf, uint32_t *pcxRead)
628{
629 RT_NOREF(pInterface, pStream, pvBuf, cxBuf);
630
631 if (pcxRead)
632 *pcxRead = 0;
633
634 return VINF_SUCCESS;
635}
636
637
638/**
639 * @interface_method_impl{PDMIHOSTAUDIO,pfnStreamPlay}
640 */
641static DECLCALLBACK(int) drvAudioVideoRecStreamPlay(PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
642 const void *pvBuf, uint32_t cxBuf, uint32_t *pcxWritten)
643{
644 AssertPtrReturn(pInterface, VERR_INVALID_POINTER);
645 AssertPtrReturn(pStream, VERR_INVALID_POINTER);
646 AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
647 AssertReturn(cxBuf, VERR_INVALID_PARAMETER);
648 /* pcxWritten is optional. */
649
650 PDRVAUDIOVIDEOREC pThis = PDMIHOSTAUDIO_2_DRVAUDIOVIDEOREC(pInterface);
651 RT_NOREF(pThis);
652 PAVRECSTREAM pStreamAV = (PAVRECSTREAM)pStream;
653
654 int rc = VINF_SUCCESS;
655
656 uint32_t cbWrittenTotal = 0;
657
658 /*
659 * Call the encoder with the data.
660 */
661#ifdef VBOX_WITH_LIBOPUS
662 PAVRECSINK pSink = pStreamAV->pSink;
663 AssertPtr(pSink);
664 PRTCIRCBUF pCircBuf = pStreamAV->pCircBuf;
665 AssertPtr(pCircBuf);
666
667 void *pvCircBuf;
668 size_t cbCircBuf;
669
670 uint32_t cbToWrite = cxBuf;
671
672 /*
673 * Fetch as much as we can into our internal ring buffer.
674 */
675 while ( cbToWrite
676 && RTCircBufFree(pCircBuf))
677 {
678 RTCircBufAcquireWriteBlock(pCircBuf, cbToWrite, &pvCircBuf, &cbCircBuf);
679
680 if (cbCircBuf)
681 {
682 memcpy(pvCircBuf, (uint8_t *)pvBuf + cbWrittenTotal, cbCircBuf),
683 cbWrittenTotal += (uint32_t)cbCircBuf;
684 Assert(cbToWrite >= cbCircBuf);
685 cbToWrite -= (uint32_t)cbCircBuf;
686 }
687
688 RTCircBufReleaseWriteBlock(pCircBuf, cbCircBuf);
689
690 if ( RT_FAILURE(rc)
691 || !cbCircBuf)
692 {
693 break;
694 }
695 }
696
697 /*
698 * Process our internal ring buffer and encode the data.
699 */
700
701 uint8_t abSrc[_64K]; /** @todo Fix! */
702 size_t cbSrc;
703
704 const uint32_t csFrame = pSink->Codec.Parms.uHz / (1000 /* s in ms */ / pSink->Codec.Opus.msFrame);
705 const uint32_t cbFrame = csFrame * pSink->Codec.Parms.cChannels * (pSink->Codec.Parms.cBits / 8 /* Bytes */);
706
707 /* Only encode data if we have data for the given time period (or more). */
708 while (RTCircBufUsed(pCircBuf) >= cbFrame)
709 {
710 cbSrc = 0;
711
712 while (cbSrc < cbFrame)
713 {
714 RTCircBufAcquireReadBlock(pCircBuf, cbFrame - cbSrc, &pvCircBuf, &cbCircBuf);
715
716 if (cbCircBuf)
717 {
718 memcpy(&abSrc[cbSrc], pvCircBuf, cbCircBuf);
719
720 cbSrc += cbCircBuf;
721 Assert(cbSrc <= sizeof(abSrc));
722 }
723
724 RTCircBufReleaseReadBlock(pCircBuf, cbCircBuf);
725
726 if (!cbCircBuf)
727 break;
728 }
729
730# ifdef VBOX_AUDIO_DEBUG_DUMP_PCM_DATA
731 RTFILE fh;
732 RTFileOpen(&fh, VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "DrvAudioVideoRec.pcm",
733 RTFILE_O_OPEN_CREATE | RTFILE_O_APPEND | RTFILE_O_WRITE | RTFILE_O_DENY_NONE);
734 RTFileWrite(fh, abSrc, cbSrc, NULL);
735 RTFileClose(fh);
736# endif
737
738 Assert(cbSrc == cbFrame);
739
740 /*
741 * Opus always encodes PER FRAME, that is, exactly 2.5, 5, 10, 20, 40 or 60 ms of audio data.
742 *
743 * A packet can have up to 120ms worth of audio data.
744 * Anything > 120ms of data will result in a "corrupted package" error message by
745 * by decoding application.
746 */
747 uint8_t abDst[_64K]; /** @todo Fix! */
748 size_t cbDst = sizeof(abDst);
749
750 /* Call the encoder to encode one frame per iteration. */
751 opus_int32 cbWritten = opus_encode(pSink->Codec.Opus.pEnc,
752 (opus_int16 *)abSrc, csFrame, abDst, (opus_int32)cbDst);
753 if (cbWritten > 0)
754 {
755 /* Get overall frames encoded. */
756 const uint32_t cEncFrames = opus_packet_get_nb_frames(abDst, cbWritten);
757
758# ifdef VBOX_WITH_STATISTICS
759 pSink->Codec.STAM.cEncFrames += cEncFrames;
760 pSink->Codec.STAM.msEncTotal += pSink->Codec.Opus.msFrame * cEncFrames;
761
762 LogFunc(("%RU64ms [%RU64 frames]: cbSrc=%zu, cbDst=%zu, cEncFrames=%RU32\n",
763 pSink->Codec.STAM.msEncTotal, pSink->Codec.STAM.cEncFrames, cbSrc, cbDst, cEncFrames));
764# endif
765 Assert((uint32_t)cbWritten <= cbDst);
766 cbDst = RT_MIN((uint32_t)cbWritten, cbDst); /* Update cbDst to actual bytes encoded (written). */
767
768 Assert(cEncFrames == 1); /* At the moment we encode exactly *one* frame per frame. */
769
770 if (pStreamAV->uLastPTSMs == 0)
771 pStreamAV->uLastPTSMs = RTTimeMilliTS() - pSink->tsStartMs;
772
773 const uint64_t uDurationMs = pSink->Codec.Opus.msFrame * cEncFrames;
774 const uint64_t uPTSMs = pStreamAV->uLastPTSMs + uDurationMs;
775
776 pStreamAV->uLastPTSMs += uDurationMs;
777
778 switch (pSink->Con.Parms.enmType)
779 {
780 case AVRECCONTAINERTYPE_MAIN_CONSOLE:
781 {
782 HRESULT hr = pSink->Con.Main.pConsole->i_audioVideoRecSendAudio(abDst, cbDst, uPTSMs);
783 Assert(hr == S_OK);
784 RT_NOREF(hr);
785
786 break;
787 }
788
789 case AVRECCONTAINERTYPE_WEBM:
790 {
791 WebMWriter::BlockData_Opus blockData = { abDst, cbDst, uPTSMs };
792 rc = pSink->Con.WebM.pWebM->WriteBlock(pSink->Con.WebM.uTrack, &blockData, sizeof(blockData));
793 AssertRC(rc);
794
795 break;
796 }
797
798 default:
799 AssertFailedStmt(rc = VERR_NOT_IMPLEMENTED);
800 break;
801 }
802 }
803 else if (cbWritten < 0)
804 {
805 AssertMsgFailed(("Encoding failed: %s\n", opus_strerror(cbWritten)));
806 rc = VERR_INVALID_PARAMETER;
807 }
808
809 if (RT_FAILURE(rc))
810 break;
811 }
812
813 if (pcxWritten)
814 *pcxWritten = cbWrittenTotal;
815#else
816 /* Report back all data as being processed. */
817 if (pcxWritten)
818 *pcxWritten = cxBuf;
819
820 rc = VERR_NOT_SUPPORTED;
821#endif /* VBOX_WITH_LIBOPUS */
822
823 LogFlowFunc(("csReadTotal=%RU32, rc=%Rrc\n", cbWrittenTotal, rc));
824 return rc;
825}
826
827
828/**
829 * @interface_method_impl{PDMIHOSTAUDIO,pfnGetConfig}
830 */
831static DECLCALLBACK(int) drvAudioVideoRecGetConfig(PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg)
832{
833 RT_NOREF(pInterface);
834 AssertPtrReturn(pBackendCfg, VERR_INVALID_POINTER);
835
836 pBackendCfg->cbStreamOut = sizeof(AVRECSTREAM);
837 pBackendCfg->cbStreamIn = 0;
838 pBackendCfg->cMaxStreamsIn = 0;
839 pBackendCfg->cMaxStreamsOut = UINT32_MAX;
840
841 return VINF_SUCCESS;
842}
843
844
845/**
846 * @interface_method_impl{PDMIHOSTAUDIO,pfnShutdown}
847 */
848static DECLCALLBACK(void) drvAudioVideoRecShutdown(PPDMIHOSTAUDIO pInterface)
849{
850 LogFlowFuncEnter();
851
852 PDRVAUDIOVIDEOREC pThis = PDMIHOSTAUDIO_2_DRVAUDIOVIDEOREC(pInterface);
853
854 avRecSinkShutdown(&pThis->Sink);
855}
856
857
858/**
859 * @interface_method_impl{PDMIHOSTAUDIO,pfnGetStatus}
860 */
861static DECLCALLBACK(PDMAUDIOBACKENDSTS) drvAudioVideoRecGetStatus(PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir)
862{
863 RT_NOREF(enmDir);
864 AssertPtrReturn(pInterface, PDMAUDIOBACKENDSTS_UNKNOWN);
865
866 return PDMAUDIOBACKENDSTS_RUNNING;
867}
868
869
870/**
871 * @interface_method_impl{PDMIHOSTAUDIO,pfnStreamCreate}
872 */
873static DECLCALLBACK(int) drvAudioVideoRecStreamCreate(PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
874 PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq)
875{
876 AssertPtrReturn(pInterface, VERR_INVALID_POINTER);
877 AssertPtrReturn(pCfgReq, VERR_INVALID_POINTER);
878 AssertPtrReturn(pCfgAcq, VERR_INVALID_POINTER);
879
880 if (pCfgReq->enmDir == PDMAUDIODIR_IN)
881 return VERR_NOT_SUPPORTED;
882
883 AssertPtrReturn(pStream, VERR_INVALID_POINTER);
884
885 PDRVAUDIOVIDEOREC pThis = PDMIHOSTAUDIO_2_DRVAUDIOVIDEOREC(pInterface);
886 PAVRECSTREAM pStreamAV = (PAVRECSTREAM)pStream;
887
888 /* For now we only have one sink, namely the driver's one.
889 * Later each stream could have its own one, to e.g. router different stream to different sinks .*/
890 PAVRECSINK pSink = &pThis->Sink;
891
892 int rc = avRecCreateStreamOut(pThis, pStreamAV, pSink, pCfgReq, pCfgAcq);
893 if (RT_SUCCESS(rc))
894 {
895 pStreamAV->pCfg = DrvAudioHlpStreamCfgDup(pCfgAcq);
896 if (!pStreamAV->pCfg)
897 rc = VERR_NO_MEMORY;
898 }
899
900 return rc;
901}
902
903
904/**
905 * @interface_method_impl{PDMIHOSTAUDIO,pfnStreamDestroy}
906 */
907static DECLCALLBACK(int) drvAudioVideoRecStreamDestroy(PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream)
908{
909 AssertPtrReturn(pInterface, VERR_INVALID_POINTER);
910 AssertPtrReturn(pStream, VERR_INVALID_POINTER);
911
912 PDRVAUDIOVIDEOREC pThis = PDMIHOSTAUDIO_2_DRVAUDIOVIDEOREC(pInterface);
913 PAVRECSTREAM pStreamAV = (PAVRECSTREAM)pStream;
914
915 if (!pStreamAV->pCfg) /* Not (yet) configured? Skip. */
916 return VINF_SUCCESS;
917
918 int rc = VINF_SUCCESS;
919
920 if (pStreamAV->pCfg->enmDir == PDMAUDIODIR_OUT)
921 rc = avRecDestroyStreamOut(pThis, pStreamAV);
922
923 if (RT_SUCCESS(rc))
924 {
925 DrvAudioHlpStreamCfgFree(pStreamAV->pCfg);
926 pStreamAV->pCfg = NULL;
927 }
928
929 return rc;
930}
931
932
933/**
934 * @interface_method_impl{PDMIHOSTAUDIO,pfnStreamControl}
935 */
936static DECLCALLBACK(int) drvAudioVideoRecStreamControl(PPDMIHOSTAUDIO pInterface,
937 PPDMAUDIOBACKENDSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd)
938{
939 AssertPtrReturn(pInterface, VERR_INVALID_POINTER);
940 AssertPtrReturn(pStream, VERR_INVALID_POINTER);
941
942 PDRVAUDIOVIDEOREC pThis = PDMIHOSTAUDIO_2_DRVAUDIOVIDEOREC(pInterface);
943 PAVRECSTREAM pStreamAV = (PAVRECSTREAM)pStream;
944
945 if (!pStreamAV->pCfg) /* Not (yet) configured? Skip. */
946 return VINF_SUCCESS;
947
948 if (pStreamAV->pCfg->enmDir == PDMAUDIODIR_OUT)
949 return avRecControlStreamOut(pThis, pStreamAV, enmStreamCmd);
950
951 return VINF_SUCCESS;
952}
953
954
955/**
956 * @interface_method_impl{PDMIHOSTAUDIO,pfnStreamGetReadable}
957 */
958static DECLCALLBACK(uint32_t) drvAudioVideoRecStreamGetReadable(PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream)
959{
960 RT_NOREF(pInterface, pStream);
961
962 return 0; /* Video capturing does not provide any input. */
963}
964
965
966/**
967 * @interface_method_impl{PDMIHOSTAUDIO,pfnStreamGetWritable}
968 */
969static DECLCALLBACK(uint32_t) drvAudioVideoRecStreamGetWritable(PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream)
970{
971 RT_NOREF(pInterface, pStream);
972
973 return UINT32_MAX;
974}
975
976
977/**
978 * @interface_method_impl{PDMIHOSTAUDIO,pfnStreamGetStatus}
979 */
980static DECLCALLBACK(PDMAUDIOSTREAMSTS) drvAudioVideoRecStreamGetStatus(PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream)
981{
982 RT_NOREF(pInterface, pStream);
983
984 return (PDMAUDIOSTREAMSTS_FLAG_INITIALIZED | PDMAUDIOSTREAMSTS_FLAG_ENABLED);
985}
986
987
988/**
989 * @interface_method_impl{PDMIHOSTAUDIO,pfnStreamIterate}
990 */
991static DECLCALLBACK(int) drvAudioVideoRecStreamIterate(PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream)
992{
993 AssertPtrReturn(pInterface, VERR_INVALID_POINTER);
994 AssertPtrReturn(pStream, VERR_INVALID_POINTER);
995
996 LogFlowFuncEnter();
997
998 /* Nothing to do here for video recording. */
999 return VINF_SUCCESS;
1000}
1001
1002
1003/**
1004 * @interface_method_impl{PDMIBASE,pfnQueryInterface}
1005 */
1006static DECLCALLBACK(void *) drvAudioVideoRecQueryInterface(PPDMIBASE pInterface, const char *pszIID)
1007{
1008 PPDMDRVINS pDrvIns = PDMIBASE_2_PDMDRV(pInterface);
1009 PDRVAUDIOVIDEOREC pThis = PDMINS_2_DATA(pDrvIns, PDRVAUDIOVIDEOREC);
1010
1011 PDMIBASE_RETURN_INTERFACE(pszIID, PDMIBASE, &pDrvIns->IBase);
1012 PDMIBASE_RETURN_INTERFACE(pszIID, PDMIHOSTAUDIO, &pThis->IHostAudio);
1013 return NULL;
1014}
1015
1016
1017AudioVideoRec::AudioVideoRec(Console *pConsole)
1018 : AudioDriver(pConsole)
1019 , mpDrv(NULL)
1020{
1021}
1022
1023
1024AudioVideoRec::~AudioVideoRec(void)
1025{
1026 if (mpDrv)
1027 {
1028 mpDrv->pAudioVideoRec = NULL;
1029 mpDrv = NULL;
1030 }
1031}
1032
1033
1034/**
1035 * @copydoc AudioDriver::configureDriver
1036 */
1037int AudioVideoRec::configureDriver(PCFGMNODE pLunCfg)
1038{
1039 CFGMR3InsertInteger(pLunCfg, "Object", (uintptr_t)mpConsole->i_getAudioVideoRec());
1040 CFGMR3InsertInteger(pLunCfg, "ObjectConsole", (uintptr_t)mpConsole);
1041
1042 return VINF_SUCCESS;
1043}
1044
1045
1046/**
1047 * Construct a audio video recording driver instance.
1048 *
1049 * @copydoc FNPDMDRVCONSTRUCT
1050 */
1051/* static */
1052DECLCALLBACK(int) AudioVideoRec::drvConstruct(PPDMDRVINS pDrvIns, PCFGMNODE pCfg, uint32_t fFlags)
1053{
1054 PDMDRV_CHECK_VERSIONS_RETURN(pDrvIns);
1055 PDRVAUDIOVIDEOREC pThis = PDMINS_2_DATA(pDrvIns, PDRVAUDIOVIDEOREC);
1056 RT_NOREF(fFlags);
1057
1058 LogRel(("Audio: Initializing video recording audio driver\n"));
1059 LogFlowFunc(("fFlags=0x%x\n", fFlags));
1060
1061 AssertMsgReturn(PDMDrvHlpNoAttach(pDrvIns) == VERR_PDM_NO_ATTACHED_DRIVER,
1062 ("Configuration error: Not possible to attach anything to this driver!\n"),
1063 VERR_PDM_DRVINS_NO_ATTACH);
1064
1065 /*
1066 * Init the static parts.
1067 */
1068 pThis->pDrvIns = pDrvIns;
1069 /* IBase */
1070 pDrvIns->IBase.pfnQueryInterface = drvAudioVideoRecQueryInterface;
1071 /* IHostAudio */
1072 PDMAUDIO_IHOSTAUDIO_CALLBACKS(drvAudioVideoRec);
1073
1074 /*
1075 * Get the Console object pointer.
1076 */
1077 void *pvUser;
1078 int rc = CFGMR3QueryPtr(pCfg, "ObjectConsole", &pvUser); /** @todo r=andy Get rid of this hack and use IHostAudio::SetCallback. */
1079 AssertRCReturn(rc, rc);
1080
1081 /* CFGM tree saves the pointer to Console in the Object node of AudioVideoRec. */
1082 pThis->pConsole = (Console *)pvUser;
1083 AssertReturn(!pThis->pConsole.isNull(), VERR_INVALID_POINTER);
1084
1085 /*
1086 * Get the pointer to the audio driver instance.
1087 */
1088 rc = CFGMR3QueryPtr(pCfg, "Object", &pvUser); /** @todo r=andy Get rid of this hack and use IHostAudio::SetCallback. */
1089 AssertRCReturn(rc, rc);
1090
1091 pThis->pAudioVideoRec = (AudioVideoRec *)pvUser;
1092 AssertPtrReturn(pThis->pAudioVideoRec, VERR_INVALID_POINTER);
1093
1094 pThis->pAudioVideoRec->mpDrv = pThis;
1095
1096 /*
1097 * Get the interface for the above driver (DrvAudio) to make mixer/conversion calls.
1098 * Described in CFGM tree.
1099 */
1100 pThis->pDrvAudio = PDMIBASE_QUERY_INTERFACE(pDrvIns->pUpBase, PDMIAUDIOCONNECTOR);
1101 AssertMsgReturn(pThis->pDrvAudio, ("Configuration error: No upper interface specified!\n"), VERR_PDM_MISSING_INTERFACE_ABOVE);
1102
1103#ifdef VBOX_AUDIO_DEBUG_DUMP_PCM_DATA
1104 RTFileDelete(VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "DrvAudioVideoRec.webm");
1105 RTFileDelete(VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "DrvAudioVideoRec.pcm");
1106#endif
1107
1108 return VINF_SUCCESS;
1109}
1110
1111
1112/**
1113 * @interface_method_impl{PDMDRVREG,pfnDestruct}
1114 */
1115/* static */
1116DECLCALLBACK(void) AudioVideoRec::drvDestruct(PPDMDRVINS pDrvIns)
1117{
1118 PDMDRV_CHECK_VERSIONS_RETURN_VOID(pDrvIns);
1119 PDRVAUDIOVIDEOREC pThis = PDMINS_2_DATA(pDrvIns, PDRVAUDIOVIDEOREC);
1120 LogFlowFuncEnter();
1121
1122 /*
1123 * If the AudioVideoRec object is still alive, we must clear it's reference to
1124 * us since we'll be invalid when we return from this method.
1125 */
1126 if (pThis->pAudioVideoRec)
1127 {
1128 pThis->pAudioVideoRec->mpDrv = NULL;
1129 pThis->pAudioVideoRec = NULL;
1130 }
1131}
1132
1133
1134/**
1135 * @interface_method_impl{PDMDRVREG,pfnAttach}
1136 */
1137/* static */
1138DECLCALLBACK(int) AudioVideoRec::drvAttach(PPDMDRVINS pDrvIns, uint32_t fFlags)
1139{
1140 RT_NOREF(pDrvIns, fFlags);
1141
1142 LogFlowFuncEnter();
1143
1144 return VINF_SUCCESS;
1145}
1146
1147/**
1148 * @interface_method_impl{PDMDRVREG,pfnDetach}
1149 */
1150/* static */
1151DECLCALLBACK(void) AudioVideoRec::drvDetach(PPDMDRVINS pDrvIns, uint32_t fFlags)
1152{
1153 RT_NOREF(pDrvIns, fFlags);
1154
1155 LogFlowFuncEnter();
1156}
1157
1158/**
1159 * Video recording audio driver registration record.
1160 */
1161const PDMDRVREG AudioVideoRec::DrvReg =
1162{
1163 PDM_DRVREG_VERSION,
1164 /* szName */
1165 "AudioVideoRec",
1166 /* szRCMod */
1167 "",
1168 /* szR0Mod */
1169 "",
1170 /* pszDescription */
1171 "Audio driver for video recording",
1172 /* fFlags */
1173 PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT,
1174 /* fClass. */
1175 PDM_DRVREG_CLASS_AUDIO,
1176 /* cMaxInstances */
1177 ~0U,
1178 /* cbInstance */
1179 sizeof(DRVAUDIOVIDEOREC),
1180 /* pfnConstruct */
1181 AudioVideoRec::drvConstruct,
1182 /* pfnDestruct */
1183 AudioVideoRec::drvDestruct,
1184 /* pfnRelocate */
1185 NULL,
1186 /* pfnIOCtl */
1187 NULL,
1188 /* pfnPowerOn */
1189 NULL,
1190 /* pfnReset */
1191 NULL,
1192 /* pfnSuspend */
1193 NULL,
1194 /* pfnResume */
1195 NULL,
1196 /* pfnAttach */
1197 AudioVideoRec::drvAttach,
1198 /* pfnDetach */
1199 AudioVideoRec::drvDetach,
1200 /* pfnPowerOff */
1201 NULL,
1202 /* pfnSoftReset */
1203 NULL,
1204 /* u32EndVersion */
1205 PDM_DRVREG_VERSION
1206};
1207
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use