{"id":13420892,"url":"https://github.com/philips/libv4l","last_synced_at":"2025-07-23T21:32:29.734Z","repository":{"id":665089,"uuid":"308180","full_name":"philips/libv4l","owner":"philips","description":"libv4l","archived":false,"fork":false,"pushed_at":"2022-12-22T02:14:48.000Z","size":363,"stargazers_count":52,"open_issues_count":4,"forks_count":28,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-07-31T22:57:01.299Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://people.atrpms.net/~hdegoede/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/philips.png","metadata":{"files":{"readme":"README","changelog":"ChangeLog","contributing":null,"funding":null,"license":"COPYING.LIB","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-09-15T20:41:59.000Z","updated_at":"2024-07-30T03:27:21.000Z","dependencies_parsed_at":"2023-01-11T15:47:32.975Z","dependency_job_id":null,"html_url":"https://github.com/philips/libv4l","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philips%2Flibv4l","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philips%2Flibv4l/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philips%2Flibv4l/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philips%2Flibv4l/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/philips","download_url":"https://codeload.github.com/philips/libv4l/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228468795,"owners_count":17924949,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T22:01:43.580Z","updated_at":"2024-12-06T13:17:17.057Z","avatar_url":"https://github.com/philips.png","language":"C","funding_links":[],"categories":["TODO scan for Android support in followings"],"sub_categories":[],"readme":"Introduction\n------------\n\nlibv4l is a collection of libraries which adds a thin abstraction layer on\ntop of video4linux2 devices. The purpose of this (thin) layer is to make it\neasy for application writers to support a wide variety of devices without\nhaving to write seperate code for different devices in the same class.\n\nAll libv4l components are licensed under the GNU Lesser General Public\nLicense version 2 or (at your option) any later version.\n\nlibv4l consists of 3 different libraries:\n\n\nlibv4lconvert\n-------------\n\nlibv4lconvert started as a library to convert from any (known) pixelformat to\nV4l2_PIX_FMT_BGR24, RGB24, YUV420 or YVU420.\n\nThe list of know source formats is large and continually growing, so instead\nof keeping an (almost always outdated) list here in the README, I refer you\nto the source, see the list of defines at the top of\nlibv4lconvert/libv4lconvert.c for the full list.\nFor more details on the v4lconvert_ functions see libv4lconvert.h.\n\nLater on libv4lconvert was expanded to also be able to do various video\nprocessing functions to improve webcam video quality on a software basis. So\nthe name no longer 100% covers the functionality. The video processing is\nsplit in to 2 parts, libv4lconvert/control and libv4lconvert/processing.\n\nThe control part is used to offer video controls which can be used to control\nthe video processing functions made available by libv4lconvert/processing.\nThese controls are stored application wide (until reboot) by using a\npersistent shared memory object.\n\nlibv4lconvert/processing offers the actual video processing functionality.\n\n\nlibv4l1\n-------\n\nThis offers functions like v4l1_open, v4l1_ioctl, etc. which can by used to\nquickly make v4l1 applications work with v4l2 devices. These functions work\nexactly like the normal open/close/etc, except that libv4l1 does full emulation\nof the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will just\npass calls through. For more details on the v4l1_ functions see libv4l1.h .\n\n\nlibv4l2\n-------\n\nThis offers functions like v4l2_open, v4l2_ioctl, etc. which can by used to\nquickly make v4l2 applications work with v4l2 devices with weird formats.\nlibv4l2 mostly passes calls directly through to the v4l2 driver. When the\napp does a TRY_FMT / S_FMT with a not supported format libv4l2 will get in\nthe middle and emulate the format (if an app wants to know which formats the\nhardware can _really_ do it should use ENUM_FMT, not randomly try a bunch of\nS_FMT's). For more details on the v4l2_ functions see libv4l2.h .\n\n\nwrappers\n--------\n\nThe functionality provided by libv4l1 for v4l1 apps and libv4l2 for v4l2 apps\ncan also be used by existing apps without modifying them. For this purpose\n2 wrapper libraries are provided which can be preloaded before starting the\napplication using the LD_PRELOAD environment variable. These wrappers will\nthen intercept calls to open/close/ioctl/etc. and if these calls directed\ntowards a video device the wrapper will redirect the call to the libv4lX\ncounterparts.\n\nThe preloadable libv4l1 wrapper which adds v4l2 device compatibility to v4l1\napplications is called v4l1compat.so. The preloadable libv4l2 wrapper which\nadds support for various pixelformats to v4l2 applications is called\nv4l2convert.so.\n\nExample usage (after install in default location):\n$ export LD_PRELOAD=/usr/local/lib/libv4l/v4l1compat.so\n$ camorama\n\n\nPrerequisites\n-------------\n\nlibv4l requires shmem file system support in the kernel (CONFIG_SHMEM).\n\n\nInstallation Instructions\n-------------------------\n\nSimple type the following commands from the libv4l-x.y.z directory\n(adjusting PREFIX as desired):\nmake\nmake install PREFIX=/usr/local\n\nNote: make install also supports the DESTDIR=... parameter for installation\ninto chroots.\n\nIf you require static libraries to also be built, these can be compiled\nalong with the dynamic equivalents by defining LINKTYPE to 'static', e.g.:\n\nmake LINKTYPE=static\nmake install LINKTYPE=static\n\n\nFAQ\n---\n\nQ: Why libv4l, whats wrong with directly accessing v4l2 devices ?\nQ: Do we really need yet another library ?\nA: Current webcam using applications like ekiga contain code to handle many\ndifferent specific pixelformats webcam's use, but that code only supports a\nsmall subset of all native webcam (compressed) pixelformats. Other current\nv4l2 applications do not support anything but rgb pixelformats (xawtv for\nexample) and this will not work with most webcams at all.\n\nWith gspca being ported to v4l2 and thus decoding to normal formats being\nremoved from the device driver as this really belongs in userspace, ekiga\nwould need to be extended with many more often chip dependent formats, like\nthe bayer compression used by the spca561 and the (different) compression used\nby the pac207 and the (again different) compression used by the sn9c102. Adding\nsupport for all these formats should not be done at the application level, as\nthen it needs to be written for each application seperately. Licensing issues\nwith the decompressors will then also become a problem as just cut and pasting\nfrom one application to another is bound to hit license incompatibilities.\n\nSo clearly this belongs in a library, and in a library with a license which\nallows this code to be used from as many different applications as possible.\nHence libv4l was born.\n\n\nQ: Under which license may I use and distribute libv4l?\nA: The libv4l libraries are licensed under the GNU Library General Publishing\nLicense version 2 or (at your option) any later version. See the included\nCOPYING.LIB file. The decompression helpers are licensed under the GNU\nLibrary Publishing License version 2 (as they are derived from kernel code)\n\n\nQ: Okay so I get the use of having a libv4lconvert, but why libv4l1 ?\nA: Many v4l2 drivers do not offer full v4l1 compatibility. They often do not\nimplemented the CGMBUF ioctl and v4l1 style mmap call. Adding support to all\nthese drivers for this is a lot of work and more importantly unnecessary\nadds code to kernel space.\n\nAlso even if the CGMBUF ioctl and v4l1 style mmap are supported, then most\ncams still deliver pixelformats which v4l1 applications do not understand.\n\nThis libv4l1 was born as an easy way to get v4l1 applications to work with\nv4l2 devices without requiring full v4l1 emulation (including format\nconversion) in the kernel, and without requiring major changes to the\napplications.\n\n\nQ: Why should I use libv4l2 in my app instead of direct device access\n   combined with libv4lconvert?\nA: libv4l2 is mainly meant for quickly and easily adding support for more\npixelformats to existing v4l2 applications. So if you feel better directly\naccessing the device in combination with libv4lconvert thats fine too.\n\nNotice that libv4l2 also does emulation of the read() call on devices which\ndo not support it in the driver. In the background this uses mmap buffers\n(even on devices which do support the read call). This mmap gives libv4lconvert\nzero-copy access to the captured frame, and then it can write the converted\ndata directly to the buffer the application provided to v4l2_read(). Thus\nanother reason to use liv4l2 is to get the no memcpy advantage of the mmap\ncapture method combined with the simplicity of making a simple read() call.\n\n\nQ: Where to send bugreports / questions?\nA: Please send libv4l questions / bugreports to the:\n   Linux Media Mailing List \u003clinux-media@vger.kernel.org\u003e\n   Subscription is not necessary to send mail to this list. If you're not\n   subscribed please put yourself in the CC of your original mail so you\n   will receive replies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilips%2Flibv4l","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilips%2Flibv4l","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilips%2Flibv4l/lists"}