Use ltmmCapture to Perform Simple Video and Audio Capture

The ltmmCapture object allows the user to capture data from video and audio hardware devices.

1. To begin simple capturing you will first need to create an instance of the ltmmCapture class. This is accomplished using the Win32 CoCreateInstance function as follows:

   C API

   IltmmCapture* pCapture; 
   CoCreateInstance(&CLSID_ltmmCapture, NULL, CLSCTX_INPROC_SERVER, &IID_IltmmCapture, (void**)&pCapture); 

   C++

   IltmmCapture* pCapture; 
   CoCreateInstance(CLSID_ltmmCapture, NULL, CLSCTX_INPROC_SERVER, IID_IltmmCapture, (void**)&pCapture); 

2. Define a window to send capture status messages:

   C API

   HWND hwndNotify; 
   #define WM_CAPTURENOTIFY (WM_USER + 1000)  
   IltmmCapture_SetNotifyWindow(pCapture, (long)hwndNotify, WM_CAPTURENOTIFY); 

   C++

   HWND hwndNotify; 
   #define WM_CAPTURENOTIFY (WM_USER + 1000)  
   pCapture->SetNotifyWindow((long)hwndNotify, WM_CAPTURENOTIFY); 

   The above code instructs the capture object to send WM_CAPTURENOTIFY messages to the window procedure for hwndNotify. The wParam parameter of the window message will contain the notification code.

   Note

   A capture can be accomplished without the use of the notification window, but the user would be required to poll the objects state to determine when the capture has finished.

3. Define a frame window for the video preview:

   C API

   HWND  hwndFrame; 
   IltmmCapture_put_VideoWindowFrame(pCapture, (long)hwndFrame); 

   C++

   HWND hwndFrame; 
   pCapture->put_VideoWindowFrame((long)hwndFrame); 

   The user is required to create the window that serves as the video frame. ltmmCapture will subclass this window, so there is no need to forward any messages to the ltmmCapture object. By default, ltmmCapture will automatically maximize the video within the frame window. The video will automatically resize when the frame window size changes.

   Note

   The notification window and the video frame window can be the same.

4. Define audio and video devices to be used as the capture source. The ltmmCapture object contains audio and video device collection objects. These objects allow the user to enumerate the registered audio and video devices and to select which devices to capture.

5. Enumerate the registered video devices:

   C API

   IltmmDevices* pDevices; 
   long lCount; 
   long i; 
   // get an interface into video devices collection 
   IltmmCapture_get_VideoDevices(pCapture, &pDevices); 
   // get the total number of registered devices 
   IltmmDevices_get_Count(pDevices, &lCount); 
   // enumerate all of the devices 
   for (i = 0; i < lCount; i++) 
   { 
      IltmmDevice* pDevice; 
      BSTR bstrName; 
      BSTR bstrFriendlyName; 
      VARIANT_BOOL fSelected; 
      // get an interface for the ith device 
      IltmmDevices_Item(pDevices, i, &pDevice); 
      // get the devices "full name" (used to uniquely identify the device) 
      IltmmDevice_get_Name(pDevice, &bstrName); 
      // get the devices "friendly name"  (used for readable display) 
      IltmmDevice_get_FriendlyName(pDevice, &bstrFriendlyName); 
      // query whether the device is currently selected 
      IltmmDevice_get_Selected(pDevice, &fSelected); 
      // 
      // add additional code here 
      // 
      // free strings 
      SysFreeString(bstrName); 
      SysFreeString(bstrFriendlyName); 
      // release the device interface 
      IUnknown_Release(pDevice); 
   } 
   // release the devices interface 
   IUnknown_Release(pDevices); 

   C++

   IltmmDevices* pDevices; 
   long lCount; 
   long i; 
   // get an interface into video devices collection 
   pCapture->get_VideoDevices(&pDevices); 
   // get the total number of registered devices 
   pDevices->get_Count(&lCount); 
   // enumerate all of the devices 
   for (i = 0; i < lCount; i++) 
   { 
      IltmmDevice* pDevice; 
      BSTR bstrName; 
      BSTR bstrFriendlyName; 
      VARIANT_BOOL fSelected; 
      // get an interface for the ith device 
      pDevices->Item(i, &pDevice); 
      // get the devices "full name" (used to uniquely identify the device) 
      pDevice->get_Name(&bstrName); 
      // get the devices "friendly name"  (used for readable display) 
      pDevice->get_FriendlyName(&bstrFriendlyName); 
      // query whether the device is currently selected 
      pDevice->get_Selected(&fSelected); 
      // 
      // add additional code here 
      // 
      // free strings 
      SysFreeString(bstrName); 
      SysFreeString(bstrFriendlyName); 
      // release the device interface 
      pDevice->Release(); 
   } 
   // release the devices interface 
   pDevices->Release(); 

6. The registered audio devices can be enumerated with the following code:

   C API

   IltmmDevices* pDevices; 
   long lCount; 
   long i; 
   // get an interface into audio devices collection 
   IltmmCapture_get_AudioDevices(pCapture, &pDevices); 
   // get the total number of registered devices 
   IltmmDevices_get_Count(pDevices, &lCount); 
   // enumerate all of the devices 
   for (i = 0; i < lCount; i++) 
   { 
      IltmmDevice* pDevice; 
      BSTR bstrName; 
      BSTR bstrFriendlyName; 
      VARIANT_BOOL fSelected; 
      // get an interface for the   ith device 
      IltmmDevices_Item(pDevices, i, &pDevice); 
      // get the devices "full name" (used to uniquely identify the device) 
      IltmmDevice_get_Name(pDevice, &bstrName); 
      // get the devices "friendly name"  (used for readable display) 
      IltmmDevice_get_Selected(pDevice, bstrFriendlyName); 
      // query whether the device is currently selected 
      IltmmDevice_get_Selected(pDevice, &fSelected); 
      // 
      // add additional code here 
      // 
      // free strings 
      SysFreeString(bstrName); 
      SysFreeString(bstrFriendlyName); 
      // release the device interface 
      IUnknown_Release(pDevice); 
   } 
   // release the devices interface 
   IUnknown_Release(pDevices); 

   C++

   IltmmDevices* pDevices; 
   long lCount; 
   long i; 
   // get an interface into audio devices collection 
   pCapture->get_AudioDevices(&pDevices); 
   // get the total number of registered devices 
   pDevices->get_Count(&lCount); 
   // enumerate all of the devices 
   for (i = 0; i < lCount; i++) 
   { 
      IltmmDevice* pDevice; 
      BSTR bstrName; 
      BSTR bstrFriendlyName; 
      VARIANT_BOOL fSelected; 
      // get an interface for the ith device 
      pDevices->Item(i, &pDevice); 
      // get the devices "full name" (used to uniquely identify the device) 
      pDevice->get_Name(&bstrName); 
      // get the devices "friendly name"  (used for readable display) 
      pDevice->get_Name(&bstrFriendlyName); 
      // query whether the device is currently selected 
      pDevice->get_Selected(&fSelected); 
      // 
      // add additional code here 
      // 
      // free strings 
      SysFreeString(bstrName); 
      SysFreeString(bstrFriendlyName); 
      // release the device interface 
      pDevice->Release(); 
   } 
   // release the devices interface 
   pDevices->Release(); 

   Note

   The only difference between enumerating video and audio devices is the initial collection object retrieved.

7. An individual device can be selected for capture by calling the device collections put_Selection function:

   C API

   IltmmDevices* pDevices; 
   // get an interface into video devices collection 
   IltmmCapture_get_AudioDevices(pCapture, &pDevices); 
   // select device 
   IltmmDevices_put_Selection(10); 
   // release collection 
   IUnknown_Release(pDevices); 

   C++

   IltmmDevices* pDevices; 
   // get an interface into video devices collection 
   pCapture->get_AudioDevices(&pDevices); 
   // select device 
   pDevices->put_Selection(10); 
   // release collection 
   pDevices->Release(); 

   The previous code selects the 10th device to be captured. You can also deselect any device by passing a 1 as the item index.

8. Define the target or output file. As demonstrated with the following code:

   C API

   BSTR bstr; 
   // create a string containing the target file path 
   bstr = SysAllocString(L"c:\\target.avi"); 
   // assign the target file path to the capture object 
   IltmmCapture_put_TargetFile(pCapture, bstr); 
   // free the string 
   SysFreeString(bstr); 

   C++

   BSTR bstr; 
   // create a string containing the target file path 
   bstr = SysAllocString(L"c:\\target.avi"); 
   // assign the target file path to the capture object 
   pCapture->put_TargetFile(bstr); 
   // free the string 
   SysFreeString(bstr); 

   The code above allocates a string containing an AVI file path and assigns the path to the capture object with a call to put_TargetFile.

9. You can now, optionally, set capture and preview properties using the ShowDialog function:

   C API

   // capture properties 
   IltmmCapture_ShowDialog(pCapture, ltmmCapture_Dlg_Capture, (long)hwndMain); 
   // preview properties 
   IltmmCapture_ShowDialog(pCapture, ltmmCapture_Dlg_Preview, (long)hwndMain); 

   C++

   // capture properties 
   pCapture->ShowDialog(ltmmCapture_Dlg_Capture, (long)hwndMain); 
   // preview properties 
   pCapture->ShowDialog(ltmmCapture_Dlg_Preview, (long)hwndMain); 

   Use the HasDialog function to test for the existence of any dialog.

10. You are now ready to start the capturing data. This is accomplished with the following code:

    C API

    IltmmCapture_StartCapture (pCapture, ltmmCapture_Mode_VideoOrAudio); 

    C++

    pCapture->StartCapture (ltmmCapture_Mode_VideoOrAudio); 

11. The notification window will be sent messages indicating the current capture progress:

    LRESULT CaptureWndProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) 
    { 
       if (msg == WM_CAPTURENOTIFY) 
       { 
          switch (wParam) 
          { 
          case ltmmCapture_Notify_Started: 
             // capture started 
             break; 
          case ltmmCapture_Notify_Complete: 
             // capture successfully completed 
             break; 
          case ltmmCapture_Notify_ErrorAbort: 
             // a capture error occurred 
             // the error code is contained in lParam 
             break; 
          case ltmmCapture_Notify_Progress: 
             // the current capture time (milliseconds) is in lParam 
             break; 
          } 
       } 
       return 0; 
    } 

12. To stop capturing the data, call the StopCapture function as follows:

    C API

    IltmmCapture_StopCapture (pCapture); 

    C++

    pCapture->StopCapture (); 

13. You can, optionally, capture a manual sequence of frames. To start a manual frame capture sequence call StartCapture as follows:

    C API

    IltmmCapture_StartCapture (pCapture, ltmmCapture_Mode_ManualFrames); 

    C++

    pCapture->StartCapture (ltmmCapture_Mode_ManualFrames); 

14. To trigger the capture of each frame call the CaptureFrame as follows:

    C API

    IltmmCapture_CaptureFrame (pCapture); 

    C++

    pCapture->CaptureFrame (); 

15. If you would like the capture object to automatically trigger the single frame captures, then you would start the capture as follows:

    C API

    // set the trigger time to 5 seconds 
    IltmmCapture_put_FrameDelay(pCapture, 5.0); 
    // start capturing frame sequence 
    IltmmCapture_StartCapture(pCapture, ltmmCapture_Mode_AutoFrames); 

    C++

    // set the trigger time to 5 seconds 
    pCapture->put_FrameDelay(5.0); 
    // start capturing frame sequence 
    pCapture->StartCapture(ltmmCapture_Mode_AutoFrames); 

    The above code will schedule a frame to be captured every 5 seconds.

16. Another variation captures a single still image as a device independent bitmap or an automation picture object. A DIB can be captured as follows:

    C API

    HGLOBAL hDIB; 
    IltmmCapture_CaptureDIB(pCapture, (long*)&hDIB); 

    C++

    HGLOBAL hDIB; 
    pCapture->CaptureDIB((long*)&hDIB); 

    The above code can be used without assigning the TargetFile. The user is responsible for freeing the returned bitmap.