UNOCONV(1)

📦
version 0.9.0 · 3 versions
, in nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

💅 UNOCONV(1) — the unoconv glow-up ✨

ok so this is the manual page for unoconv, and honestly? she's iconic. converting docs from literally anything LibreOffice can open into literally anything LibreOffice can spit out. no cap. 🦋

✨ NAME ✨

unoconv — convert any document from and to any LibreOffice supported format 🎀

🌸 SYNOPSIS 🌸

unoconv [options] file [file2 ..]

unoconv --listener [--server SRV] [--port PRT] [--connection CON]

💖 DESCRIPTION 💖

unoconv is a command line utility that can convert any file format that LibreOffice can import to any file format that LibreOffice is capable of exporting. it's giving "universal translator but make it office docs" fr fr 💫

she uses LibreOffice's UNO bindings for non-interactive conversion of documents, which means she needs a LibreOffice instance to talk to. so if she can't find one, she'll just start her own instance for temporary usage — very main character, very self-sufficient 💅. and if you want, you can start a "listener" instance to use for subsequent connections, or even for remote connections. the way that just works 😭👑

🎀 OPTIONS 🎀

  • -c, --connection — the UNO connection string, used by the client to connect to a LibreOffice instance, or used by the listener to make LibreOffice listen. 🫶 Default connection string is "socket,host=localhost,port=2002;urp;StarOffice.ComponentContext"
  • -d, --doctype — specifies the LibreOffice document type of the backend format. the possible document types are: document, graphics, presentation, spreadsheet. 🍓 Default document type is 'document'.
  • -e, --export — sets specific export filter options (related to the LibreOffice filter you're using). for example, for the PDF output filter you can specify: -e PageRange=1-2. see the EXPORT FILTERS section, bestie 💜
  • -f, --format — specifies the output format for the document. you can get a list of possible output formats per document type by using the --show option. ⭐ Default document type is 'pdf'.
  • -F, --field — add or replace a user-defined text field with a value. e.g. -F Client_Name="Oracle" ✨
  • -i, --import — sets specific import filter options (related to the LibreOffice import filter based on the input filename). see the IMPORT FILTERS section 💖
  • -I, --input-filter-name — specifies the input filter name, used when the file ending doesn't match the file type. e.g. -I odt 🎀
  • -l, --listener — starts unoconv as a listener for unoconv clients to connect to. 👑
  • -M, --meta — add or replace document metadata with a value. e.g. -M Author="Dag Wieers" 🦋
  • -n, --no-launch — by default, if no listener is running, unoconv will launch its own (temporary) listener to make sure the conversion works. this option will abort the conversion if no listener is found, rather than starting our own listener. 🙈
  • -o, --output — if the argument is a directory, put the converted documents in this directory. if multiple input files are provided, use it as a basename (and add output extension). otherwise use it as the output filename. 🌸
  • --password — provide a password to decrypt the document 🔐
  • --pipe — use a pipe as an alternative connection mechanism to talk to LibreOffice 🫧
  • -p, --port — port to listen on (as listener) or to connect to (as client). 🍓 Default port is '2002'.
  • --preserve — keep timestamp and permissions of the original document 💫
  • -s, --server — server (address) to listen on (as listener) or to connect to (as client). 🌈 Default server is 'localhost'.
  • --show — list the possible output formats to be used with -f. 👀
  • --stdin — read input file from stdin (filenames are ignored if provided) 📥
  • --stdout — print converted output file to stdout 📤
  • -t, --template — specify the template to use for importing styles from. this can be very useful if you have a corporate identity you have to apply to every document you distribute. 💼✨
  • -T, --timeout — when unoconv starts its own listener, try to connect to it for an amount of seconds before giving up. increasing this may help when you receive random errors caused by the listener not being ready to accept conversion jobs. 😭
  • -v, --verbose — be more and more and more verbose. 🗣️🗣️🗣️

🌈 ARGUMENTS 🌈

you can provide one or more files as arguments, and each of them gets converted to the specified output format. that's it, that's the argument. periodt 💅

🧚 IMPORT FILTERS 🧚

depending on the used input file, a different LibreOffice import filter is automatically used by unoconv. this import filter can be influenced by the -i option, which — depending on the filter used — accepts different arguments. 🦋

ngl it's not always clear what import filter options you can provide, but the import dialog in LibreOffice for the filter you are using might give a good indication as to what you can expect as import filter options. 👀

the reference is LibreOffice's documentation, and for spreadsheets it is described at: http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Filter_Options but we will look into some examples. 💖

⭐ DEFAULT IMPORT FILTER OPTIONS ⭐

the default import filter for many imports (e.g. Lotus, dBase or DIF) accepts the input encoding-type as the only argument, so if you require utf-8 (76) you can do:

-i FilterOptions=76

for a list of possible encoding types, you can use the above link to find the possible options. 🔗

  • FilterOptions

🎀 TEXT IMPORT FILTER OPTIONS 🎀

the Text import filter accepts a FilterOptions setting holding the input encoding. ✨

  • FilterOptions

🍓 CSV IMPORT FILTER OPTIONS 🍓

the CSV import filter accepts a FilterOptions setting, and the order is: separator(s),text-delimiter,encoding,first-row,column-format 🌸

for example you might want to use this for a real comma-separated document:

-i FilterOptions=44,34,76,2,1/5/2/1/3/1/4/1

which will use a comma (44) as the field separator, a double quote (34) as the text delimiter, UTF-8 (76) for the input encoding, start from the second row and use the specified formats for each column (1 means standard, 5 means YY/MM/DD date). 🗓️

if you like to use more than one separator (say a space or a tab) and use the system's encoding (9), but with no text-delimiter, you can do:

-i FilterOptions=9/32,,9,2

for a list of possible encoding types, you can use the above link to find the possible options. 🔗

  • FilterOptions

🔥 EXPORT FILTERS 🔥

in contrast to import filters, export filters can have multiple named options, although it is not always clear what options are available. it all depends on the version of LibreOffice. the export dialog you get in LibreOffice might give you a clue about what's possible — each of those widgets represents an option. 👑💅

💜 TEXT EXPORT FILTER OPTIONS 💜

the Text export filter accepts a FilterOptions setting holding the output encoding.

  • FilterOptions

the order of the arguments is: encoding,field-seperator,text-delimiter,quote-all-text-cells,save-cell-content-as-shown ✨

🫶 CSV EXPORT FILTER OPTIONS 🫶

the CSV export filter accepts various arguments, and the order is: field-seperator(s),text-delimiter,encoding 🦋

for example you might want to use this for a real comma-separated document:

-e FilterOptions=44,34,76

which will use a comma (44) as the field separator, a double quote (34) as the text delimiter, UTF-8 (76) for the export encoding, start from the second row and use the specified formats for each column (1 means standard, 5 means YY/MM/DD date). 🗓️

if you like to use more than one separator (say a space or a tab) and use the system's encoding (9), but with no text-delimiter, you can do:

-e FilterOptions=9/32,,9

for a list of possible encoding types, you can use the above link to find the possible options. 🔗

  • FilterOptions

💀 PDF EXPORT FILTER OPTIONS 💀

the PDF export filter is likely the most advanced export filter in its kind, with a myriad of options one can use. 😭 the export filter options are described in a separate document, or on LibreOffice's wiki at:

http://wiki.services.openoffice.org/wiki/API/Tutorials/PDF_export

for example one can specify: -e PageRange=1-2 ✨

here is a list of all options — however, for more details please look in filters.txt: 📄

  • AllowDuplicateFieldNames
  • CenterWindow
  • Changes
  • ConvertOOoTargetToPDFTarget
  • DisplayPDFDocumentTitle
  • DocumentOpenPassword
  • EmbedStandardFonts
  • EnableCopyingOfContent
  • EnableTextAccessForAccessibilityTools
  • EncryptFile
  • ExportBookmarks
  • ExportBookmarksToPDFDestination
  • ExportFormFields
  • ExportLinksRelativeFsys
  • ExportNotes
  • ExportNotesPages
  • FirstPageOnLeft
  • FormsType
  • HideViewerMenubar
  • HideViewerToolbar
  • HideViewerWindowControls
  • InitialPage
  • InitialView
  • IsAddStream
  • IsSkipEmptyPages
  • Magnification
  • MaxImageResolution
  • OpenBookmarkLevels
  • OpenInFullScreenMode
  • PageLayout
  • PageRange
  • PDFViewSelection
  • PermissionPassword
  • Printing
  • Quality
  • ReduceImageResolution
  • ResizeWindowToInitialPage
  • RestrictPermissionPassword
  • Selection
  • SelectPdfVersion
  • UseLosslessCompression
  • UseTaggedPDF
  • UseTransitionEffects
  • Watermark
  • Zoom

🌈 GRAPHICS EXPORT FILTER OPTIONS 🌈

  • Height
  • Resolution
  • Width

🎀 BMP EXPORT FILTER OPTIONS 🎀

  • Compression
  • RLEEncoding

🦋 JPEG EXPORT FILTER OPTIONS 🦋

  • ColorDepth
  • Quality

🍓 PBM/PGM/PPM EXPORT FILTER OPTIONS 🍓

  • Encoding

✨ PNG EXPORT FILTER OPTIONS ✨

  • Compression
  • InterlacedMode

💖 GIF EXPORT FILTER OPTIONS 💖

  • InterlacedMode
  • Transparency

🧚 EPS EXPORT FILTER OPTIONS 🧚

  • ColorFormat
  • Compression
  • Preview
  • Version

👑 EXAMPLES 👑

you can use unoconv in standalone mode — that means that in absence of a LibreOffice listener, it will start its own: 💫

unoconv -f pdf some-document.odt

one can use unoconv as a listener (by default localhost:2002) to let other unoconv instances connect to it: 🫶

unoconv --listener &
unoconv -f pdf some-document.odt
unoconv -f doc other-document.odt
unoconv -f jpg some-image.png
unoconv -f xsl some-spreadsheet.csv
kill -15 %-

this also works on a remote host: 🌐

unoconv --listener --server 1.2.3.4 --port 4567

and then connect another system to convert documents: 🔥

unoconv --server 1.2.3.4 --port 4567

🌸 ENVIRONMENT VARIABLES 🌸

  • UNO_PATH — tells unoconv which LibreOffice pyuno installation it's supposed to be vibing with. like, which one. be specific bestie. example: /opt/libreoffice3.4/basis-link/program 💅

✨ EXIT STATUS ✨

okay so here's the tea 🫖 — normally the exit status is 0 if the conversion ran successful. slay. but if an error has occured, the return code is most likely an error returned by LibreOffice (or its interface, called UNO), however — and this is the annoying part 😭 — the error never translates to something meaningful. it's giving cryptic. it's giving "figure it out yourself."

in case you like to decipher the LibreOffice errCode (main character energy honestly 👑), look at:

http://cgit.freedesktop.org/libreoffice/core/tree/tools/inc/tools/errcode.hxx
http://cgit.freedesktop.org/libreoffice/core/tree/svtools/inc/svtools/sfxecode.hxx
http://cgit.freedesktop.org/libreoffice/core/tree/svtools/inc/svtools/soerr.hxx

using the above lists, the error code 2074 means:

Class: 1 (ERRCODE_CLASS_ABORT)
Code: 26 (ERRCODE_IO_INVALIDPARAMETER or SVSTREAM_INVALID_PARAMETER)

and the error code 3088 means:

Class: 3 (ERRCODE_CLASS_NOTEXISTS)
Code: 16 (ERRCODE_IO_CANTWRITE)

so yeah. now you too can decode the vibes 💀

🦋 SEE ALSO 🦋

convert(1), file(1), odt2txt

🎀 BUGS 🎀

unoconv uses the UNO bindings to connect to LibreOffice, and — plot twist — in absence of a usable socket, it will start its own LibreOffice instance with the correct parameters. it just does that. it's independent like that ✨

Note Please see the TODO file for known bugs and future plans. the lore is documented 📓

💜 REFERENCES 💜

unoconv is very useful together with the following tools:

a list of possible import and export formats is available from:

🌈 AUTHOR 🌈

Written by Dag Wieers, <dag@wieers.com[1]>

⭐ RESOURCES ⭐

Main web site: http://dag.wieers.com/home-made/unoconv/

🧚 COPYING 🧚

Copyright (C) 2007 Dag Wieers. Free use of this software is granted under the terms of the GNU General Public License (GPL). iconic licensing behavior tbh 🫶

👑 AUTHOR 👑

  • Dag Wieers <dag@wieers.com> — Author.

🍓 NOTES 🍓

  1. dag@wieers.com — mailto:dag@wieers.com

and that's a wrap bestie 💖 this was unoconv version 0.4, dated 20 october 2010, page UNOCONV(1) — go forth and convert literally everything ✨💅🌸

📦 where this page comes from